Christian Heilmann

Posts Tagged ‘articles’

How to write an article or tutorial the fast way

Saturday, January 2nd, 2010

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.

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 chapter of the developer evangelism handbook).

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:

Turning a nested list into a tree navigation

See the demo, download the code

Considering the audience

How do tree navigations work?

Allowing for styling

Accessibility concerns

Start with the minimal markup

Add styling

The dynamic CSS class switch

Add the script

Event delegation vs. Event handling

Adding a configuration file

Other options to consider

See it in action

Contact and comment options

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.

Turning a nested list into a tree navigation

See the demo, download the code

working demo, code on github

Considering the audience

who needs tree navigations? where are they used?

How do tree navigations work?

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?

Allowing for styling

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

Accessibility concerns

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

Start with the minimal markup

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

Add styling

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

The dynamic CSS class switch

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

Add the script

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

Event delegation vs. Event handling

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

Adding a configuration file

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

Other options to consider

Dynamic loading of child branches.

See it in action

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

Contact and comment options

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 chapter of the developer evangelism handbook.