Authoring Knowledge Base Articles
Most people who wind up managing documentation aren’t professional writers. Indeed, most aren’t writers at all. They’re usually the newest employee, or the person who dislikes documentation the least. If you are one of these people, congratulations! The task of knowledgebase management was thrust upon you, and now you’re in charge.
But don’t worry. It’s easier than it seems, and with a few guidelines you’ll have this elephant digested in no time.
Clear and Concise
If you take in no other advice, at least make sure you are clear and concise. I gave you that rhyme deliberately, because I want it to stick. It’s the number one rule of business writing, technical writing, and any other kind of functional writing.
In 1946 George Orwell said, “Never use a long word where a short one will do”. Despite the evolution of the English language, that statement still holds true.
Keep your sentences simple and short wherever possible. A good test is to read it out loud. If you need to take a breath partway through, it’s too long.
Knowledgebase articles are generally instructional, so they should be written in the present tense.
Avoid the Curse of Knowledge
When we know our processes and systems well, we often assume everyone else does too. We forget that some of our readers may not know what we’re talking about. Here’s how you can avoid that problem.
As you write each article, imagine a new employee reading it. Have you left something unsaid that seems obvious to you, but wouldn’t be to them?
If you’re in the support business, write from the end-user’s perspective. How would they describe the problem?
Just the Facts, Ma’am
Some organisations, particularly in the finance industry, can be subject to rigorous auditing. A third party may review your process documentation for compliance. If your knowledge base allows it, you may also have the option of publishing articles to an online self-help for end-users.
The last thing you want is for a derogatory comment to be published.
Stick with describing the facts. No in-jokes and no opinion.
Bust the Jargon
The industry or organisation you are in may use a lot of jargon. While it’s acceptable sometimes, try to avoid it as much as possible to avoid confusing your readers. If you must use it, provide a quick reference guide to commonly-used jargon and acronyms.
Make the Connections
Some knowledge base systems let you reference related articles. Hyperlinks and “tooltip” links are even better. If yours has this feature, use it! Make it easy to gather supporting information.
Link to definitions, contacts, other related issues and articles, and external websites with relevant information.
If you can, attach photographs, screenshots, maps or other documents that help describe the problem or environment.
Responsible Tagging
All online knowledge base systems are searchable—even simple Word documents. So give each article you write a relevant, meaningful heading and use
7