Skip to content

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.