Structure the content
Most of our 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. In journalism, this technique is called the "inverted pyramid."
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 to use the Schematron to validate your document and find errors
Use:
Validate 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:
- Can be hard to read and search for
- May duplicate other content on your site
- Mean that content is not where people expect to find it.
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.