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.