A knowledge base can be an awesome resource or an appalling waste of space. The difference often comes down to its design. Consider these key points before you start to write content.
Know your users
If you don’t know what your users are trying to do with your software, you’re working in the dark. You’re stuck writing articles about how the software architect envisaged them using the product. That’s usually off-base, because human beings are contrary creatures.
Get feedback from your users
Integrate at least one way for users to give you feedback on articles, and preferably on the entire knowledge base. You could add:
- Thumbs-up/thumbs-down options on each article.
- A chat-bot.
- A form that asks what the user is trying to do, and forwards their answers to customer service (and you!).
- Star ratings.
Use feedback from your users
Incorporate user feedback into your documentation development life cycle. Plan to use it to improve current articles and identify information gaps in your knowledge.
Map articles to functionality
You need to be able to find information gaps in your knowledge base. That means you’ll need some way of mapping software functionality to articles that document it. This can be as simple as an Excel spreadsheet or as complex as a UML diagram. Check your map every time a piece of functionality is modified. Update it whenever functionality is added.
Tag every article
Make sure that your knowledge base software allows you to tag articles. Then, use that tagging functionality! Tags can be used to:
- Make searching the database easier.
- Specify the version of software an article was written for.
- Map articles to areas of functionality (note: this might be an internal, development tag).
- Automatically create useful ‘Related Articles’ links.
- Help search engines to index the knowledge base.
One problem; one answer
A knowledge bases isn’t an online version of a user manual. It isn’t supposed to slowly lead users through an entire system from A to B. Instead, a knowledge base should primarily exist to answer specific problems that users might encounter. Each article should:
- Answer a single question.
- Link to other articles where it presumes prior knowledge
(eg. “Log into the Telecoms system” should include a link to an article on how to do just that)
- Make it easy to find the actual steps to follow.
Code change ➡ doc change
When a developer changes a bit of functionality, your knowledge base is out of date. Suddenly one or more articles are incorrect. Design a process where code changes alert the documentation team to change specific articles. An automatic system is ideal, but not always feasible. Use your functionality-documentation map.
Have a retirement process
Outdated articles are the scourge of knowledge bases. They’re also a huge pain in the bum. Search engines often prioritise older articles over newer ones, adding to the problem. Put together a process for removing old articles when your company:
- no longer supports a version of the software.
- supersedes functionality.
- obsoletes functionality.
Want to learn more about designing a knowledge base? I found this HelpScout article interesting: 10 Knowledge Base Examples That Get It Right.