Modern Network Architecture

Mar 16 2013   8:18PM GMT

How to write a Knowledge Base (KB) “How to…” Document

James Murray James Murray Profile: James Murray

As a Seattle IT Consultant, I review a lot of documentation.  Not because the clients I work with have documentation, but because I am training technicians to write their own documentation for the first time.  Documentation is one of my favorite subjects.  I think that a technician can increase their income faster because they are willing to do what most IT experts seem unwilling or unable to do.  It takes time to get better and I often feel like an English teacher.  Recently I have been working with a client building a knowledge base for Tier 2 and 3 technicians.

Here’s an example I’ve run into on several past Fortune 500 companies.  Tier 4 technicians solving the same problem over and over again.  Tier 4 technicians or problem managers if you go with ITIL definitions, should only be troubleshooting Unknown issues.  So if they are troubleshooting an issue they’ve seen before, there is a problem.  Now the owner is paying for root cause analysis on the same issue four or five times.  For one of my clients it was actually 1000’s of times each month.  The problem wasn’t with the tier 1 technician.  It was with the lack of documentation by the tier 4 technician.  Once the tier 4 technician understood the problem, a KB article should be written for the tier one technician so the tier 1,2 or 3 technician can solve the problem in the future.

By writing “How to…” documents the Tier 4 technician can teach the tier 2 and 3 technicians to solve problems before they become tier 4 issues.  Here’s a very high level layout for a how to document.

Simple Outline for writing a “How To…” documentation

Body Section 1

Define the problem <Documents that fall under the “How to…” Describe the steps for accomplishing tasks as simple as setting up an email account in Outlook or as complex as installing a set of servers.  The first Section in the body outlines the problem and high level steps for solving the problem. In this first section outline the prerequisite, the audience and other issues the reader might need to know before starting the process.>

Body Section 2

<In the second paragraph outline a high level process.  Advanced audiences will be able to pickup the solution without reading the detailed instructions.>

(Note: Mistakes many technicians make Not understanding the needs of their audience Not formatting the steps in a clear way Assuming that the reader knows as much as the author)

Body Paragraph 3

In this section the details are written out.  Writing documentation in High level steps is much simpler for advanced readers.  Then indented below each high level step, giving further instructions for completing these high level steps


Summary description

Detailed Description

Step 1: High level description

Details to accomplish step 1

Step 2:  High level description

Details to accomplish Step 2


Technician’s notes:

By creating High level steps, if the technician already knows how to do the step, the technician doesn’t have to read the details of the step and can move to the next step.  Technicians that need the details can run through all the steps.  For an outline go to Seattle IT

Check out this site for layouts you can copy to document your own network.  If you need someone to create a knowledge base for you check out,   I am creating a list of document descriptions you’ll need to document your systems including, How to…, Settings, Topology and other documents you’ll want for your network.


 Comment on this Post

There was an error processing your information. Please try again later.
Thanks. We'll let you know when a new response is added.
Send me notifications when other members comment.

Forgot Password

No problem! Submit your e-mail address below. We'll send you an e-mail containing your password.

Your password has been sent to:

Share this item with your network: