Writing for the web

Simple is not stupid

Writing very simple texts is hard work. Writing stupid texts is less hard. Consider the following traits of simple texts:

• Writing in simple terms takes a lot of work and thorough understanding of the subject matter. You need to be very familiar with the topic to be able to explain it in very easy terms.
• If you explain things in as easy as possible terms you make sure that you reach the largest amount of readers.
• Simple wording allows non-native speakers to get a chance to understand what the whole thing is about and maybe spend some time with a translation tool to make it work for them.

There is however a fine line between explaining complex things in simple terms and sounding condescending. Have someone else look over your texts to avoid this issue.

Read and re-read what you’ve written (take breaks in between) and make it easier in every iteration. Comparisons with real life objects work very well to simplify complex matters.

Example: At the last Open Hack day of Yahoo I talked to several press people and they were thoroughly confused about the concept of a hack day and open APIs. I explained it this way: “If Yahoo were a car company our newest models would be here totally dismantled and we'd allow people to play with the parts. Maybe they'll find a cool new way to assemble them that is the breakthrough we wanted in making cars greener and more efficient.”

Say what it is - don’t sugar-coat it

Your heading and introductory text are the most important things of a blog post. Both determine how easy it will be to find the post in the future.

Newspapers have conditioned us to write clever, witty and interesting headlines with pop references and alliterations. That is fun, but you already have bought the paper once you read them. Web headlines become links and bookmarks and need to make sense without the rest of the text. For a technical blog post state what the post is about – do not try to be too clever. Pop references are even worse as these don’t translate well to other cultures.

So do you want to be creative and witty for a minute or do you want to provide valid information for several months?

Blog posts should work like news items in radio:

• At the start of any post state what happened, where and how.
• Continue to explain what is coming in the post.
• Then go into details

This will prevent any confusion and put interested people on the way to find out more.

If you wonder where your blog headline needs to make an impact just think of RSS readers and personal homepages as shown in this screen shot:

Each of these grey lines are a headline of an article or blog post and this is where it counts to be informative. Does your headline both tell the reader what is going on and entices them to click it?

Size matters

Technical writing for online use is about keeping things short and to the point. People are busy and want the facts.

So in order to write great posts, write them, read them, delete what is not needed, read again, delete more and so on. If you cannot take anything away any longer, you’ve reached the point of publication.

If you have a lot to cover, why not split it up into several posts? This will allow you to tease at the end of the first post that the next will be published in a few days and give you repeat visitors and readers on your blog.

Add media

If you can, add relevant media to the post. An introductory photo invites the eye and lures the brain into reading what happened. We’re lucky that these days embedding video, audio and slides is as easy as copy+paste.

Embedding ties our information together in a nice, easy to digest bundle. It also allows visitors to skim over the post the first time and come back to take in the rest (watch the video, download the podcast) later.

This also helps people who have a hard time reading but are very much capable of listening or seeing.

When embedding media make sure to also write explanatory text – images need good alternative text and videos at least a description of what they show.

Tip: Slides get much better by providing a text alternative or your notes. SlideShare automatically creates text versions of your slides for you. Personally I start with my notes and then create my slide decks from them – that way I do always have an HTML version to link to from the deck.

Structure your content

Structuring your content is very important. Giving readers landmarks to take in your information one chunk at a time allows them to skim the post before deciding to read it and as people are busy this goes down really well.

You achieve this by using a hierarchical heading structure. This will also help people with assistive technology like screen readers to jump from section to section quickly .If you add IDs to the headings people can bookmark parts of the document and send links to friends that will bring them directly to where they want to be.

Structuring a text also means using short sentences. It means paragraphs dealing with one thing at a time. It means using lists to explain step-by-step processes or give an overview of what is available. For large documents it also means providing a table of contents which allows people to jump directly to where they need to be.

Time-stamp your content

If you eat food past the “best before” date you get sick. If you don’t time-stamp your publications they will be considered great forever – even if they are harmful by the technical standards of the future. They’ll be quoted – sometimes badly – and re-iterated over and over again and taken as gospel.

Example: When I started as a web developer tables for layout were the only way to build a site. And you had to know a lot of tricks to make those work for Netscape 3 and IE4 and other fun browsers. I published a few articles on how to do that. Nowadays table layouts are counterproductive to web development and actually render much slower on modern browsers. If my articles didn't have a date on them maybe people would still consider them relevant. All the “CSS layout is too hard” posts out there surely hint at that.

Our technical environment moves at breakneck speed. What was “best practice” half a year ago might very well be “considered harmful” now. So let’s make sure that readers know when a certain document was written before following its advice even now.

Cite to prove

The last, very important point in this section is to cite other sources and link to content you have built upon. By citing other sources (and reading them of course) you validate your thoughts and facts. Readers don’t have to trust you blindly – they can make up their mind by comparison.