Tips for writing good content

How people read on the web

People read differently on the web than they read print media.

"On the web, however, most of us scan information, jumping from one point of interest to the next, hoping to trip over some relevant facts. In fact, according to a study by the Norman Nielsen Group, your visitors will only ready between 20 and 28% of the words on your site."

—"8 Tips for Better Readability" by Roby Collinge

This information is not specific to online documentation, it is about information on the web in general. Nonetheless, we should consider that information about reading on the Web at least partly applies to reading online documentation as well.

So:

  • Readers on the web often do not read, they scan (skim).
  • Additionally, they often do not read entire manuals, they google for the information they are looking for and start reading there.

Tip 1: Write for online reading

  • Make it easier for the reader who has not read previous pages.
  • Make sure, the title is clear.
  • Text with good formatting is easier to scan (see the next two tips)

Tip 2: Use paragraphs

In any case, avoid long "walls of text". Give the eye something to cling to.

Tip 3: Use subheaders

Look at this page

Imagine removing all the subheaders and then reading it.

Tip 4: Think about your audience

What is the typical target audience of your text? Put yourself in the shoes of your readers while writing. Find someone from your target audience to read your text and give feedback.

Tip 5: Use a consistent and clear vocabulary

Use specific (not ambiguous) language.

Tip 6: Write simple, short sentences

Keep the text as short as possible. Edit out anything that can be omitted without loss:

"Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts."

—Strunk & White: "The Elements of Style

Tip 7: Use a spellchecker

ヒント

Use a spellchecker that also points out grammar mistakes and gives recommendations for style improvements. Try out this free online check by Grammarly.

Tip 8: Use Stack Overflow to learn

Yes, Stack Overflow can be a good teacher. Or, we should add, its users are.

You may notice, there are some good answers on StackOverflow, ideally formatted for readability, very well written and structured. If you have not signed up for StackOverflow yet, do it now and start writing questions and / or answers.

Advanced Stack Overflow users often use number or unnumbered lists and other formatting elements.

Of course, it is better to keep the text on Stack Overflow as short as possible, but if the text is longer than a paragraph, lists help to structure the text and make it more readable.

Additionally, some users are very good at explaining things.

See how this highly voted answer by Mysticial on branch prediction uses a railroad junction analogy.

You can use the advanced search to search for highly voted answers, but note that number of votes correlates with a number of factors. Quality is not always the decisive factor (it also depends on whether the information is relevant for a high number of users).

Tip 9: Read other documentation

  • Ask yourself questions: What works for you, what doesn't?

Here are some tips:

Tip 10: Read your own content

When you write new content, finish it, wait a few days, and then read it again!

Additional Resources

You can find more in the Resources section.