How to write an article or tutorial the fast way

As you know if you come here often, I am a very prolific writer and churn out blog posts and articles very quickly. Some people asked me how I do that – especially as they want to take part in “Project 52″:http://project52.info/.

Well, here is how I approach writing a new post/article:

Step 1: Find a problem to solve

Your article should solve an issue – either one you encountered yourself and always wanted to find a solution to on the web (this is how I started this blog) or something people ask on mailing lists, forums or Twitter.

Step 2: Research or code (or both)

The first step is the research of the topic you want to cover. When you write, you don’t want to get side-tracked by looking up web sites. Do your surfing, copy and paste the quotes and URLs, take the screenshots and all that jazz. Put them in a folder on your hard drive.

If your article is a code tutorial, code the whole thing and save it in different steps (plain_html.html, styled.html, script.html, final.html,final_with_docs.html). Do this step well – you will copy and paste part of the code into your article and when you find mistakes then you need to maintain it in two spots again. Make sure this code can be used by others and does not need anything only you can provide (for more tips check the “write excellent code examples”:http://developer-evangelism.com/code.php chapter of the “developer evangelism handbook”:http://developer-evangelism.com/).

Step 3: Build the article outline

The next thing I do is write the outline of the article as weighted headlines (HTML, eh?). This has a few benefits.

• You know what you will cover and it allows you to limit yourself to what is really needed.
• You will know what follows what you are writing and already know what you don’t need to mention. I myself tend to get excited and want to say everything in the first few lines. This is bad as it doesn’t get the readers on a journey but overloads them instead.
• You can estimate the size of the overall article
• You can write the different parts independent of another. If you get stuck with one sub-topic, jump to one you know inside-out and get this out of the way.

It would look something like this:

<h1>Turning a nested list into a tree navigation</h1>

<h2>See the demo, download the code</h2>

<h2>Considering the audience</h2>

<h3>How do tree navigations work?</h3>

<h3>Allowing for styling</h3>

<h3>Accessibility concerns</h3>

<h2>Start with the minimal markup</h2>

<h2>Add styling</h2> 

<h2>The dynamic CSS class switch</h2>

<h2>Add the script</h2> 

<h3>Event delegation vs. Event handling</h3> 

<h3>Adding a configuration file</h3>

<h2>Other options to consider</h2> 

<h2>See it in action</h2>

<h2>Contact and comment options</h2>

Step 4: Fill in keywords for each section

For each of the sections just put in a list of keywords or topics you want to cover. This will help you to write the full text.

<h1>Turning a nested list into a tree navigation</h1>

<h2>See the demo, download the code</h2>

working demo, code on github

<h2>Considering the audience</h2>

who needs tree navigations? where are they used?

<h3>How do tree navigations work?</h3>

How does a tree navigation work? What features are common? How to allow expanding a sub-branch and keep a link to a landing page?

<h3>Allowing for styling</h3>

keep look and feel away from the script, write a clean css with background images.

<h3>Accessibility concerns</h3>

Consider keyboard access. cursor keys, tabbing not from link to link but section to section and enter to expand.

<h2>Start with the minimal markup</h2>

clean HTML, simple CSS handles, not a class per item

<h2>Add styling</h2> 

show the style, explain how to alter it - show a few options

<h2>The dynamic CSS class switch</h2>

the trick to add a class to a parent element. allows for styles for the dynamic and non-dynamic version. Also prevents the need for looping 

<h2>Add the script</h2> 

Performance tricks, safe checking for elements, structure of the script

<h3>Event delegation vs. Event handling</h3> 

One event is enough. Explain why - the menu will change as it will be maintained elsewhere.

<h3>Adding a configuration file</h3>

Take all the strings, colours and parameters and add it to a configuration file - stops people from messing with your code.

<h2>Other options to consider</h2> 

Dynamic loading of child branches.

<h2>See it in action</h2>

Show again where it is and if it was used in live sites

<h2>Contact and comment options</h2>

Tell me where and how to fix things

Step 5: Write the full text for each section.

As said before you can do that in succession or part by part. I find myself filling in different sections at different times. Mostly I get out the laptop on the train and fill in a quick section I know very well on a short ride. That means it is out of my way.

Step 6: Add fillers from section to section

I then add a sentence after each section that sums up what we achieved and what we will do next. This is not really needed but great for reading flow.

Step 7: Read the lot and delete what can be deleted

The last step is to read the whole text (probably printed out as you find more mistakes that way) and see how it flows. Alter as needed and remove all the things that seemed a great idea at the first time of writing but seem superfluous now. People are busy.

Step 8: Put it live and wait for the chanting groupies

Find a place to put the article, convert it to the right format, check all the links and images and you are ready to go.

More, please, more!

More tips on the style of the article itself are also listed in the “Write great posts and articles”:http://developer-evangelism.com/writing.php chapter of the developer evangelism handbook.

Tags: articles, blogging, evangelism, p52, project52, structure, tips, writing

This entry was posted on Saturday, January 2nd, 2010 at 4:37 pm and is filed under General. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.