Structure the content

Most documentation is read online. Here are some tips for presenting it.

Important information first

Readers tend to scan text until they find the information they need. No matter how carefully you lay out and write the content, most people only read 25 percent of it. This shows the importance of getting content right.

Put the most important information in the first two paragraphs. That's the section users are most likely to read.

Break up text

A wall of text overwhelms readers. Use subheads and bullet points as they provide clear narrative structure for readers in a hurry. Put information-rich words at the beginning of the phrase, and use the active voice.

Instead of:

How the Schematron is used to validate your document and find errors


Validating with the Schematron

Tables are a good way to visualize a lot of data. Long paragraphs with a lot of names, dates, and other information are much more difficult to scan than this:

Dates covered Report Due
January 1--March 31 April 15
April 1--June 30 July 15
July 1--September 30 October 15
October 1--December 31 January 31

What about FAQs?

FAQs are easy to write and structure---too easy. They:

If you're thinking about posting FAQs, review the content and look for ways to improve it. Unless there's a compelling reason, avoid FAQs.