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."
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.
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 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."
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!
Daniele Procida: "What nobody tells you about documentation (May 19, 2017) - A very good blogpost about different kind of manuals.
"8 Tips for Better Readability" by Roby Collinge is a very good resource. However, some of the tips do not concern you as a writer. They are only relevant for theme development. As a writer, skip right down to tip 5.
Strunk & White: "The Elements of Style is a classic. Many principles still apply.
You can find more in the Writing Resources section.