Sunday 5 February 2017

The Basics: 12 Steps to Writing a Great Knowledge Base Article

Knowledge Base (KB) articles are normally technical and as such in the realm of the technical writer.  Where an FAQ might encourage you to try a new product or feature, a KB article helps a user get past a problem when they're already using that product or feature.  So if FAQs represent "sales self service", KB articles represent "support self service".  

With this in mind, you should focus your initial efforts on writing KB articles that will answer the most asked support questions.  This will provide the greatest return on investment for your documentation.  Once you've built up a library of articles, you should try to move to a position where new KB articles are written in response to incoming customer questions.  Ideally, if a customer asks a question once, and the answer isn't publicly available, you'll publish a KB article answering that question within a short period of time

But how do you write a good KB article?  Well, the basics of writing good documentation don't change, but there are a few things which are more important when writing KB articles.  Let's got through them below.

1. Know the subject

First and foremost, don't publish an article unless you're certain it's correct.  This applies to experienced staff who think they know exactly how the product works just as much as it applies to less experienced staff.  As an example, I once wrote a KB article on the possible permutations of accounts and permissions that could be setup for a web application and IIS, but I'd misunderstood the scope of the question.  The result was a rewrite that took some time because the people who understood the technical side were difficult to get hold of, and more importantly it confused a couple of customers, which was the worst possible outcome.  This leads directly to #2.

2. Proof read for technical correctness

Get 2 different people to proof read it if necessary.  There's no shame in asking for the input and oversight of people who are more technically qualified or experienced than you.  As a technical writer you are expected to understand technical issues so you can communicate them, but you're not expected to know all of the technicalities of a product better than anyone else.  That's why you have architects, designers, administrators, installation experts, etc.  Use them.

3. Iterate.  Then iterate.  Then iterate again.

Preferably find someone who doesn't know how to perform the actions you're explaining and ask them follow the instructions through.  If they don't understand it first time, or they ask about an ambiguity, alter the article until it's clear and unambiguous.  This is not a negative step, it's a necessary part of writing a good piece of technical documentation.  A KB article can deal with complex issues that can be even more complex to explain, so the first draft of a KB is unlikely to be the last. Write, test, alter, repeat.

4. Don't overestimate the reader's knowledge

AKA Know Your Audience.  If you're writing for a data entry operator then take the time to explain things that seem obvious to you.  Remember, if you weren't knowledgeable enough about the software to write technical documentation about it, you wouldn't be writing KB articles.  You know more than your target audience so walk them through things if necessary.

5. Don't underestimate the reader's knowledge

AKA Know Your Audience part II.  If you're writing for a System Administrator then try to avoid the whole "teaching your grandmother to suck eggs" thing.  It's a tricky balancing act but if the target audience is (supposedly) technically competent or highly knowledgeable then they won't thank you for wasting their time or making them feel stupid.

6. Make it modular

If you find yourself walking through the same process in more than one KB article, then write a separate article that just deals with that process and link to it in future articles.  This saves you time and helps the user by not cluttering up articles with information that's duplicated elsewhere.


The old "Keep It Simple, Stupid" acronym. In the case of KB articles, this means that you should try to capture one task or process in one article.  Don't try to cram too much in, and don't shy away from writing a series of articles that deal with the distinct stages of a complicated process.  At the start of each article in the series tell the reader that they should be familiar with the information in the preceding articles before continuing.  This allows them to feel that they are making progress and allows you to write self-contained articles that just deal with the problem in hand. 

8. Step-by-step

Don't explain a process in a paragraph.  Use a numbered list, and make 1 numbered point = 1 step.  As a rule of thumb, if there is more than 1 action in 1 numbered point then turn it into 2 numbered points.

This goes hand-in-hand with points 4 and 5 about knowing your audience.  If you're writing for System Administrators who know the product, don't be afraid to write:

"1. Log into the application and navigate to screen x"

Equally, if you're writing for potentially inexperienced users don't be afraid to write:

"1. Log into the application."
"2. Navigate to screen x.  In a default setup this will be located at System > Parameters > screen x"

Generally paragraphs should be used to explain something from a conceptual perspective and numbered lists should be used to explain actions and steps.

9. One Step, One Screenshot

If you write an article with 10 steps, use a good screenshot for each one if it will help the user.  A picture tells a thousand words when you're trying to understand something new.  Users aren't short of the bandwidth needed to download a 20kb png file and I know that the use of screenshots is controversial, but don't preclude them on a point of principle.

10. One Screenshot, One Lawsuit

I can't say this enough: Check your data.  I have seen a KB article published by a colleague who'd taken screenshots using a live database, and those screenshots included identifiable information about customers.  If you have access to live databases, or, as if sometimes the case in development teams, a customer database provided for the purposes of testing, then check, check and recheck your data.  If in doubt, create dummy data, and if you can't then obfuscate any data or consider not using screenshots.  Using live or customer data is a one way ticket to a lawsuit for your company and quite possibly the sack for you.

11. Quality, not Quantity

Yes, it looks great if you bang out 20 KB articles in an afternoon, but it doesn't look so great a week later if 19 of them have been the cause of support tickets.  You're supposed to be helping support, not making more work for them.  You can't rely on a proofreader to weed out every mistake, because it may be that you're the person who's supposed to be an expert on whatever it is you're writing about (this is especially the case if you're not a technical writer and you're adding KB articles).  Writing KB articles is not a fast and easy way to look good.  It is difficult to write well, and even more difficult to write well at speed.  Take your time, think about what you're doing, focus on getting it clear and correct.

12. Spell check is not optional

If you're a technical writer you'll know this, but if you're not then hear this: You can't spell.  Seriously.  Technical writers do this for a living and we spellcheck everything.  Learn to love Word and its spell checking, grammar checking, and little squiggly lines.  These is no excuse for a spelling error in a KB article and it will make you look incompetent.  It will also make your company look incompetent and reflects badly on everyone.  Don't be the person who makes your users wonder how on Earth your company can write decent code if they can't even use a spellchecker.

KB articles are a great way to take the load off support and give customers the power to fix their own problems.  Get it right and you'll find the rewards far outweigh the costs.