Ted Cox is a Linux nerd, a cyclist, and LexBlog's Technical Writer. He enjoys burritos and writing bios in the third person.

As Jared wrote earlier, we employ several tools to make support documentation easily available to our users. In addition to those tools making our software easier to use, the content and structure of each article should help users quickly complete a task or understand a concept. How a piece of text contributes to a reader’s comprehension is what technical writers refer to as readability.

After joining LexBlog in 2016, I quickly focused on how we write, organize, and share customer-facing help articles. One particular task has taken me a year and counting: structuring all of our docs for readers who don’t have time to read.

 

Some points about our users

When I write or edit articles, I have to remember these points about our users:

  • On the web, people don’t read. They scan. User eyes are very good at skipping to the content they need.
  • Our users are busy. When looking at a help article, they need to find relevant content quickly. Nobody has time to read four pages about, well, anything.
  • Our users are diverse. Some of our users are seasoned web developers. Others have never logged into a blog in their life. Some may use accessibility software to help them read text on a page. Others may not speak English as their first language, so translation software helps them with the text.
  • Users get frustrated. Often a user doesn’t look at documentation until something goes wrong. The person reading a help article may already be confused, frustrated, or lost.

 

Structuring and writing support articles

It may sound like a contradiction — writing for people who don’t read everything on the page — but a few simple techniques improve an article’s readability. These are the general rules I follow when writing or editing help articles:

  • Keep it consistent. Our docs should follow the same, predictable format. New users who need more details can read more of the document. Experienced users who just need a refresher can skip straight to the parts they need.
  • Put important information up top. User eyes spend more time at the top of a webpage. So we put important messages higher in the docs. It’s a good idea to tell a baker to preheat the oven before they mix the batter.
  • Keep it short. Articles are brief and focused. Short, descriptive titles should tell you what the article is about. We limit sentences to 25 words, while paragraphs are generally limited to four sentences. If a concept requires more explanation, we may link to another source.
  • Use headers and lists. Clear, useful headers help a reader’s eyes skip to the information they need. Lists group together similar ideas or instruct users on how to perform a task. Using both of these elements can help break up a wall of text.
  • Use simple words. Technical writing is delightfully boring. We avoid jargon and pretension.

 

Learn more about readability

As I mentioned, restructuring our support articles is an ongoing task. Users like fixing their own problems, and clear, readable documentation can help them do so.

Here are some of the sources I regularly consult about writing for readers on the web: