How To Write IT Technical Documentation

By Sam Grier

Documentation plays an important part in Information Technology. Work

instructions, help desk scripts, knowledge bases, and vendor instructions
are only a few examples.

The key to writing good technical documentation is in the format of the

document. No matter how good the information is, if it is not well formatted it can be
difficult to use. Documentation should be easy to read, easy for the reader to
understand and well organized. Writing good technical documentation is time
consuming, but well worth the effort.

Steps to Good Documentation

There are some essential steps to take in order to produce quality documentation.

What Is The Purpose?

Determine what the purpose of the documentation is such as work instructions, vendor
instructions, knowledge base or other type. This will help you define the content, the
format and in some cases the media you will use.

Who Are You Writing For?

Knowing who will be reading the documentation will help you determine the depth and
word usage. You want to write the documentation at the level of the person reading it.

Collect Information

Even if you are an expert in the area gather all of the information you can find on the
subject. You may need to interview or get the assistance of others to help you gather
the needed information. Manuals, user guides and online resources are very useful.

Write an Outline
Start with an outline of the document indentifying the different sections of the document.
This will help guide you as you fill in the blank spaces with more detail.

Write The First Draft

Working from the outline begin to fill in each section with details. Don’t worry about
formatting or editing at this point. Here you want to get down all of the information that
will be in the document.

Revise and Format

Now it is time to polish the document and format it. A good rule of thumb is you will end
up removing more than you add if you wrote the first draft correctly. Wait until you have
a final draft before you format the document.

The Four Essential Parts

Depending on the subject most technical documentation should be broken down into
four areas.

 Title
 Section
 Steps
 Appendix

The Title

The title is what the documentation is about. For example

Network Support – Troubleshooting Connectivity Issues

The Section

The document should be divided into sections. Each section contains detailed step-by-
step instructions.

Section 1 – Ping The Remote Station

Section 2 – Examine Event Logs

The Steps

Each section will contain detailed step-by-step instructions on how to perform the action
for that section.

1.1 Use the ping –t command to ping the remote station

1.2 Watch the ping statistics. If you detect lost packets go to Appendix 3

The Appendix

The appendix is used to place more information or detailed instructions on how to deal
with specific issues. For instance in the above example if lost packets were detected
when you ping the remote station you would refer to Appendix 3. Appendix 3 would
detail what to steps to take when lost packets are detected.

By using this approach you keep your steps clean and easy to follow. You do not want
to clutter them with detailed instructions on how to handle each problem or issue that
may arise. Use the Appendix for that.

Key Points

Always Use Numbered Steps

When writing documentation you should always used numbered steps. They are easier
to follow and allow you to better support the documentation when used by someone
else.

For instance you create installation instructions for a vendor. They call in and ask about
a step in the process they are having a problem with. Without numbered steps you may
get a question like “where it says to connect the light blue console cable, included with
the router…”.
With numbered steps you would get the question “At step 3.4 it says connect the light
blue console cable, included with the router…”. Now you do not have to hunt through
the document looking for what the caller is referring to. You know they are at step 3.4
which is easy to find.

K.I.S.S.

Yes, keep it simple stupid. A very important philosophy when it comes to writing good
technical documentation. Do not go into long detailed explanations or steps.
Documentation should be short, clear and easy to follow. This makes it easy for the
user and helps eliminate possible errors due to details that are not needed.

Use a Template

Part of a good documentation system is consistency. By using a template for each type
of documentation you write your readers will find it easier to use. Software such as
Microsoft Word allows you to save a document as a template. Once you have a good
template use it for each new document you write. It will save you time and will produce
consistent looking documentation.

Organize With a Reference System

Now where is the documentation on trouble-shooting connectivity issues? Maybe it is

under N for network, or C for connectivity. Avoid this problem by using a letter and
number reference system for your documentation.

As you create documentation keep a log sheet. Assign each set of documentation with
a letter number system. For instance NS-21 Network Support – Troubleshooting
Connectivity Issues. NS for network support and this is document number 21 in the
network support reference library.

You can generalize such as PR – process instructions, WI – work instructions, AP –

administrative processes, GP – general processes and so on. Log each set of
documentation including the reference number (NS-21), the title of the documentation
(Network Support – Troubleshooting Connectivity Issues), the location of the soft copy
of the document, the author of the document and the last revision date.

When you print out your documentation you can put it in a binder and label it. By having
a reference system you can line them all up NS-1, NS-2, NS-3 and so forth. Put a copy
of the log sheet on the location the documentation is stored for easy reference.

Take Away, Literally

There are many reasons to document something. One of the most important reasons is
to retain the knowledge of key personnel. If someone leaves the company they take all
of their knowledge of your systems with them. Having documented processes and
procedures helps you retain some of that knowledge.

I would suggest that you identify key personnel and task them to document their
processes and procedures now. Even if they have poor writing skills you can always
give the information to someone else to revise. The goal is to document their knowledge
so you may retain it.