How to write a technical knowledge base for your website
Thinking about creating a knowledge base for your business? This blog covers the fundamentals of how to write useful and thorough guides, and how to produce the right level of technical writing for your website.
What is a technical knowledge base and why do you need one?
A knowledge base is a way of managing technical information so that it can be referenced and shared. A technical knowledge base normally holds information on how to use features or processes, answers to technical questions and troubleshooting.
If your business has an application, developed software or unique functionality on your website, some good technical writing to make clear how to use it can be useful for a number of reasons:
- It provides a repository for information on issues, questions and their resolutions. This means that when an issue has been solved, the resolution will be recorded, which saves time for the future.
- Technical features and issues are explained in layman’s terms – providing a useful reference point for both staff and customers.
- It helps customers to resolve issues and find answers to queries, without the need to contact customer support.
- It can also help your helpdesk staff answer questions more quickly when people do contact customer support.
The following sections will look at how you should structure your knowledge base, and how to write the technical details, with examples of best practice.
How to structure your technical knowledge base
Your knowledge base will be less effective if people can’t find what they are looking for, so the way you structure your content is important.
Choose a clear layout that allows people to get to the information they are seeking as quickly as possible. Divide content into sections and provide an obvious method of searching.
Example: The Groove Knowledge Base is clearly laid out and has a prominent search box to help users find exactly what they need.
Well-written titles will help people to find, reference and share your knowledge base articles. Always use clear, straight-forward language and try to include any keywords that users may be searching for. Be specific so that people know they have found the right article from the title.
Example: Evernote’s titles are clear, action-driven and written with the language of the user.
Evernote also adds tags to articles, which can be a helpful aid for finding the right information.
Create a standard format to ensure consistency and ease of reading. Use commonly used conventions wherever possible. For example, you may specify that paths (when given for users to refer to) should always be consistently written as follows:
File > Save As… > Save as jpg
How to write knowledge base entries
Create a clear process for people writing new knowledge base entries to use – this will help ensure new questions, issues and resolutions are always logged. Explanations of features are likely to be laid out differently, but questions and issues will probably follow a standard three-step format.
1. Details of the problem or question.
This is particularly important for issues. Make sure you include the following information:
a. What is the problem? Be sure to include enough detail when describing the problem so people know they have found the same issue they are experiencing.
b. Why is this happening? Explain what has caused the error and steps you are taking to resolve it.
c. How do I know if I have the same issue? Some information you might like to include at this point are error messages or the exact circumstances known to lead to the problems.
2. Response – answer or solution.
Next, outline the answer to the question or solution to the problem. If the solution is complex, break it down into manageable steps, explaining any technical terms.
If screenshots or videos will help illustrate the solution, include these in your response.
Example: Wistia include screenshots throughout their help guidance.
3. Next steps.
Hopefully, the majority of readers will have found the information they were looking for or resolved their issue, but for those that haven’t, ensure you offer a way out. Where can they go to get help if the fix doesn’t work? If people do need to contact you, make this option obvious. It’s also a good idea to include links to similar or related issues, in case those might help them resolve their problem before calling customer support.
Example: Help Scout have a link to get in touch plus related content at the end of every article.
Technical writing tips
Write to be understood
Use simple language even in designated technical writing for your user base. No one wants to spend time wading through technical jargon, they want to find the solution to their problem as quickly as possible.
Research has shown even specialists prefer to read in plain English, rather than complex language, with 80% of lawyers stating they would rather read commonly understood language than legal terms. In fact, the more educated the person and the more specialist their knowledge, the greater their preference for plain English.
Write for reading on a screen
As when following best writing practice for FAQs, you should write knowledge base content for ease of reading on a screen. Don’t write in one big block, break content into chunks for easy scan-reading.
Example: Basecamp breaks down their articles into easy-to-scan steps.
Proof read and test solutions
Before new articles go live, double check that they work and other people can follow along. You can do this internally, and in addition, you could also invite feedback through comments in order to improve your support information.
Conclusion – keep your knowledge base alive
Hopefully this blog has provided you with a good introduction to writing a technical knowledge base for your website. One final key tip – your knowledge base is only as good as its last update. View it as a living resource, and try to ensure that all entries are reviewed on a regular basis and updated as questions, answers and solutions change.