When I speak with other IT Professionals about documentation I usually get a few less favorable reactions such as the rolling of the eyes, or the deep sighs. Most IT Professionals know the importance of having good documentation but find that creating and building a plan to develop it can be a pain staking process. I find that many people don't even know where to begin when starting the journey of documenting IT policies, procedures, and operating manuals. If your organization is at the point to where an outside consultant can't simply walk in and tweak or update something on the fly then it's time to look at creating IT Documentation.

1. Where do I start?

I get this question all the time and my answer is simple, "security". Evaluate how you are securing your IT environment, who has access to what information and develop a plan to limit the exposure. Here's a simple yet effective way to create control levels, purchase a flash drive and install an encryption program on it such as TrueCrypt if the flash drive does not currently have one installed. Create a text based document with all the administrator usernames and passwords using something like notepad, (I say text based because in case of fire or some other acts that are out of your control you may need immediate access to the information and using a program not found on another computer can defeat the purpose of the drive) and save them to the drive. Encrypt the drive and print a copy of the passphraseused on the drive, place that sheet in a sealed envelope, sign it and give it to an Officer or Equivalent in the company such as the CEO or VP and have them store it in a safe location. Now that the drive is secured and encrypted place that drive in an envelope, sign it and give it to the HR department to store in a Fire Proof safe. Now you have a starting point to securing your network, create a system to change the passwords at least semi-annually as well as the passphrase.

2. Should documentation be long or short?

There are pluses and minuses to both strategies and here is what I tell people. Short documentation needs to be agile and efficient but leaving out key information can cause for the documentation to be faulty. You have to look at this from an outsider coming in, they should be able to look at the documentation and understand the objective. On the other hand documentation that is long and overly detailed is usually caused by writers who include conceptual practices that may not be fully tested. If you are in this boat then I would tell you to treat the documentation like a test, verify that the information on the document is correct and appropriate to achieve the end result.

3. System Documentation can act like an image

They say that pictures speak a thousand words, well so does system documentation. Printing documentation directly from the source such as Router Configurations, Switch Setting and so forth can prove to be extremely valuable in a pinch and allow you a window into to configuration when everything was working correctly.

4. Allow Documentation be place in multiple formats

Here's one that most people don't think about, when you have completed your documentation create multiple formats of this documentation to be used securely in different mediums such as Print, Electronic, and Online if you have a company Intranet available. Documentation should be made available to your IT staff so delivering them in such a fashion helps expedite the problem and allows them to resolves issues more efficiently.

5. Updating Documentation

When trying to develop a plan on when to update your documentation look at your SDLC or Software Development Life Cycle to determine when updates are appropriate. Following this cycle allows you to keep your documentation up to date with the current software you are using. Nothing is worse then trying to update newer software with outdated documentation.

6. Proof the Documentation

One of the biggest problems with documentation is the lack of proofing by an outside individual, sure you may understand what it meas to  "IPL the Server" but more then likely the person reading the documentation may not. Make sure you have someone proof read the documentation and are able to follow your directions and what you are trying to accomplish. Don't just like steps without briefly explaining what you are trying to do, this can only complicate matters if issues arise with the person following the documentation not understanding what they are trying to do.

7. Treat Documentation as a Job Duty

Documentation should be just as important to you as planning your next project phase or supporting your network. Without the proper documentation doing any of those other tasks only create more hardship if the need to find out how something on your network is working or configured. Good documentation leads to a better ran IT department that can address issues in a smoother fashion. IT may be your life but documentation is your job.

8. You may not be right to write!

You may have all the technical degrees and certificates but if you are not able to bring your processes and protocols to paper you might need assistance from someone who may not be as technically inclined but can get across the important information to get the job done. If you have trouble you may want to invest in taking a writing course to help you hone in on skills that will allow you to put your thoughts from your pen to your paper.

9. Use Flowcharts and Technical Grids to tell a story!

There are those who create "Flow Charts" and then there are those of you who create "FLOW CHARTS", meaning sometimes they become so overly clustered with line segments that you can't determine which way is up without a legend or Northern Arrow. I have ran across people who get so detailed with their flow charts that they actually have to create documentation just to try and understand it all, keep it clean and simple and if the need arises number and index your charts to correlate with your documentation.

10. Watch out for the Overlap

If you plan on delegating your documentation development to a team of members, try and watch out for the overlap of information. Besides the redundancy of the documentation, errors or discrepancies can and will occur throughout the documentation. Make sure you proof everything to weed out the information that may cause an overlap and create a happier less hostile working environment when someone reads documentation that may not be completely accurate or explained in a way that is not as easy to follow or understand.