Writing knowledge base articles is inherent to almost every customer support team. Tom Ewer wrote an amazing post on “How to Create User-Friendly WordPress Instruction Manuals for Clients”. The article contains a lot of detailed tips & examples for WordPress manuals. But Tom’s advice may be applied to writing any kind of manual, not just knowledge base articles. Therefore, we decided to extract general instructions for writing a great manual for practically anything.
1. Get ready for writing
Before you do anything, you have to really put yourself in the mindset of the reader. The manual scope will strongly depend on the type of audience for which you are writing. So you may want to clearly define what your readers need from the knowledge base articles. Asking your target audience may be the best way to get this information.
Writing down a general profile (persona) of your knowledge base articles reader is also a good idea.
Then you will be able to tailor your knowledge base articles to the needs of your clients as closely as possible. The more thorough you can be with regard to your specific client base, the more your clients will be able to get out of your manual.
2. Begin with an introductory overview
A good way to go about easing people into any topic is to start off by introducing the absolute basics. If you are writing a complex manual (e.g. knowledge base articles on how to use your product), you should try to briefly cover topics like:
- What … is
- What people do with …
- Why … is so popular
- Why anyone can learn …
- What you will learn about … from the manual
Keep it simple. You want to establish the right tone of voice here in order to ensure that your clients will be able to follow along easily. It may even be more appropriate to tackle this introductory part after you’ve finished drafting out the main part of the content. Providing a summary of the manual will become less complicated.
3. Break up the content into sections
To avoid confusing your user, arrange your knowledge base articles content properly. Clear structure is also necessary for covering more detailed points and transition into related sections. So, keep all related topics in one section, if possible.
Tip: If you are writing knowledge base articles for a software product, using sections as “navigation” and “natural user on-boarding flow” may be a good start.
Your main sections might include:
- Registration
- Logging in
- Dashboard
- …
- Users
- Settings
- Plugins
- …
4. Add subsections to the main sections
Quite often, there is a lot to learn about your product. That’s why it’s smart to break up your big sections into subsections. Some sections will naturally have more subsections than others.
For example, logging in is pretty straightforward but still requires a few areas to be covered:
- Accessing the login page
- Logging into your account with your username and password
- Retrieving a forgotten username or password
- Logging out of your account
That’s about as much as you need in terms of the very basics of logging in, and you could even condense it all into one or two subsections if you wanted. In contrast, the main section affiliated with the use of your service/product is likely going to be your biggest section(s) to tackle.
Remember to keep your main sections and subsections in line with the needs of your target reader. Regular referring to a reader profile in the preparation stage, will help you keep the right scope.
Don’t overwhelm your users with information or functions you know they don’t necessarily need to know or use.
Just make sure you’re not skipping on important areas in your knowledge base articles.
5. Use a visual step-by-step process
A big chunk of your manual is likely going to be screenshots, and you should aim to show every consecutive step the reader should follow, and avoid missing any step or confusing the reader. When you’re planning out how to display your screenshots, consider the following:
- Incorporate numbered steps for each screenshot (or a combination of screenshots) and supporting text to make it easy for the user to follow in the right order.
- Write the content of the entire manual in landscape orientation to facilitate full-page screenshots that are of high quality and very readable.
- Use a photo editing or graphic design program to add labels, arrows, circles, extra notes, and anything else to draw attention to certain areas of the screen shot.
- Use bright colors to emphasize those labels, arrows, and other edited components on the screenshots
You may decide to use an animated GIF image or even a video to demonstrate the flow of the steps. In such case, here are some tips for you:
- Conduct a test before you start recording your video and write down a simple list of the steps in demonstrated scenario. It will help you while you are recording.
- Pay attention to the pace of the video – not too slow, but not too fast. To help yourself, you may still narrate aloud what you’re doing while you’re recording, even if you decide not to record the audio stream.
- Use software to highlight your mouse cursor position and clicks. This will allow you to avoid having to circle around the button you’re going to click. If your video is without any audio narration whatsoever, be sure that the audio of the mouse clicks is not likely to irritate your viewer.
- A narrated video is always better than a silent one. So, even if it feels strange listening to yourself, ask someone else to give you honest feedback. In most cases, presenters don’t sound bad at all – it’s all just in their heads.
6. Support the visuals with descriptive explanations
Visuals are crucial, but they can still create a lot of confusion without appropriate explanations. Before delving straight into the step-by-step process of a particular activity, first explain what you are trying to accomplish and why it should be accomplished. Any particular features included in the process should also have an explanation so the reader knows what they’re used for – not just how to use them.
When writing out your text, you should aim to:
- Break up long paragraphs as much as possible.
- Use screenshots directly beneath the corresponding text as opposed to grouping them together after one or more pages of text.
- Define any topic terminology that may be used throughout the text.
- Add links to other resources that users can refer to for more information.
7. Include helpful extras
Obviously, the instructions are the meat of your knowledge base articles, and they’re what matters most. But there are lots of additional sections you can add for a more complete and well-rounded user experience.
Table of Contents
If your knowledge base is going to have a lot of sections and subsections of instructions, you want to make it as easy as possible for users to find the instruction set they need for any given problem. Having a complete table of contents of all sections and subsections and their corresponding pages is absolutely crucial.
In the case of HTML pages you may consider including IDs to section headings to be referred directly and even allow readers to simply copy a “deep link”. Enabling the user to quickly navigate back to the TOC will be very useful as your web page gets longer or if your manual is eventually published in the form of an HTML page.
Section summaries
At the end of every section (or even every subsection if you so choose) you can include a brief summary of what the user has learned and the main points that have been covered. In some cases, you may find it better to place summaries at the beginning of a section.
FAQ section
Users love FAQ sections, and it’s one of the best places to present solutions to the most common problems. If you need ideas for your FAQs, try looking around at what people are asking about your topic in forums.
Keep in mind that a long FAQ list is hard to search through and read. Keep your FAQs limited or provide the reader with an effective way of working with your extensive list of FAQs.
Resources section
There’s only so much information you can include in your knowledge base articles, and even if you make it as detailed as you can, there will probably be more to read and learn. Adding a Resources section with links to helpful articles and video tutorials will help point users in the right direction when they need more help.
Glossary section
Complete beginners aren’t going to have a clue about technical terms. Even though you should explain their meanings the first time you present them in the instructions, having a glossary section in (the back of) your manual for quick reference is extremely useful.
Quick start guide
It is a good idea to develop an extra little manual or section (that goes at the beginning of your manual), to help users who are short on time and want instructions that get straight to the point. A “Quick Start” guide is made to do just that, by summing up only the essentials. Set hard limits on reading time, and keep them in mind while you are writing the Quick start guide to truly keep it quick to read.
Support section
Where can your users get help when they’re stuck? Can they contact you or someone else? Is there a forum or a support desk they should refer to? When neither the knowledge base article nor the extra online resources can answer a user’s questions, they should be able to find out how and where to get help from an actual person.
8. Get someone to review your manual
Before you finalize your manual and publish it digitally or even in paper form, you should get at least one other person’s input on it to find out if it serves the user as well as it should. Even if you think you’ve covered everything, someone else might notice something you’ve missed or that needs clarification – especially if that person has no prior experience with the main topic of your manual.
9. Update regularly
Last but not least: don’t underestimate the effort necessary for keeping your knowledge base articles up to date. Pay close attention to developing a reliable process for updating your documentation. While you can get away with handing out a manual that’s just slightly behind the times, leaving it for too long will no doubt create issues for users. Problems will only snowball once readers start noticing big differences between the outdated information and their current product.Here’s a quick checklist for good knowledge base articles:
- Do you have at least one introductory overview?
- Do you divide your manual into logical sections and subsections?
- Do you group similar topic into one section?
- Do your (sub)sections follow the natural flow/process of the user (when relevant)?
- Do you only go from basic to advanced topics?
- Do you have enough step-by-step visuals (or videos) included?
- Are your visuals always accompanied by descriptive explanations?
- Do you have a Table of Contents, Search or Navigation?
- Should you include section summaries?
- Do you have a FAQ section with the most common questions?
- Could you simplify or enhance your manual with a Resources section?
- Did you explain all the technical terms the first time you used them?
- Should you have a Glossary section?
- Would it be useful to have a Quick start?
- Do you have all available contact channels for support listed?
- Do you have a solid & effective process for keeping your manual up to date?
BONUS TIP: if you want to dig more into this topic, find more interesting stuff at INSTRKTIV.
How did you like this blog?
