Writing Clear and Digestible Knowledge Base Articles

Getting users to read text is a difficult problem. There's a fine line between an article helping a user become successful or a user finding themselves more confused than they were before.

Here are some tips on writing your articles with users in mind.

Keep articles short and readable

When a user visits your knowledge base they're looking to skim content and find an answer. It's unlikely they will read the whole article, word by word.

With this in mind, keeping articles short and to the point makes sense.

• Aim for < 500 words per article
• Use bulleted lists and/or ordered lists to break up information
• Use categories and subcategories to split up articles
• Keep paragraphs shorter than two sentences
• Use callouts to highlight important or useful information
• Insert images to illustrate a point or add an example
• Longer articles should provide a table of contents for easy navigation
• Use tables for complex information

The structure your article

An article can quickly become out of control if you're not sure what to write. If a user knows what to expect from your format of your articles, it'll be easier for them to read the next when a problem arises.

If you're unsure, here's a simple example of how to write out your articles.

• Introduction. A short snippet about what the article solves for the user.
  • What will the article help me with?
  • Do I need to know anything before I get started?
• Instructions. An ordered list with step by step instructions on what actions the user needs to take.
  • Provide images inline to provide context
  • If it's complicated, create a short video instead