Best Practices for Creating IT Documentation

Good documentation does not happen by chance. In a world where everyone is a publisher, the ability to create documentation has never been easier. But creating quality documentation that provides value to the reader takes practice and discipline. The best documentation helps transfer knowledge to the reader while anything less often causes confusion. The same ideas apply to creating IT documentation whether you are mapping your infrastructure, drafting server and application dependencies or preparing for a software audit. The best time to begin the process is well before you need it, but don’t fret if you haven’t started, because listed below are best practices for creating IT documentation. Begin with a Plan In the planning phase you should define the following:

• The purpose and scope of the project
• What resources are available
• Timeline and deliverables of the project
• A budget for the project

If the documentation is meant for colleagues outside of IT, you will also need to consider the audience and their technical understanding as you plan. Even the format will be dictated by the audience. For example, if you decide to place all documentation on an obscure SharePoint site, you should not expect anyone outside IT to know it exists. The goal here is to set expectations for exactly what documentation needs to be created and who is responsible for it. Your plan should include specific dates and names, or it will be more of a template than an actual plan. A plan also holds people accountable. A good plan will reduce the amount of time spent on creating documentation because everyone knows what will and what will not be covered. Use Clear and Concise Language

This is a lot easier said than done, even when you plan to avoid acronyms, buzzwords, and company-speak. Do not merely consider your audience but know your audience and what they will and will not comprehend. If that means having someone in finance or HR read through a draft, do it. Ask them to circle any words they don’t understand. Most people will skip through your documentation if they don’t understand what you’re trying to share with them. That might not sound important, but what if you are documenting the password and security policies? Everyone in the company needs to understand them, and the risks are great if they tune out before grasping the concepts of safe computing. Use Visuals   Nobody enjoys reading through blocks and blocks of texts without anything to break up the monotony. Many people assume technical documentation must be boring, but it doesn’t have to be. Use visuals to help others grasp complex topics. Providing a visual allows the mind to tackle the issue from a different angle. The goal here isn’t to create the next IKEA manual. Some concepts are better off detailed and then augmented with a visual that should aid rather than distract from the topic at hand. Today’s presentation software includes tools for creating visuals, and standalone products such as Microsoft Visio provide many options to create compelling visuals. Update and Refine The only way to know if your documentation is accurate is to use it. Challenge your employees to complete tasks using only the new documentation. Do not be surprised to find holes because you have done the task so many times you skimmed over parts. IT documentation is never finished. Each document should be considered a living document that will be updated and improved as things change. Who oversees updating the documentation? That really depends on the size of the project. For example, you might want one person to manage the network topography documentation because it must remain current each day. Other documentation can probably be updated each month or quarter depending on the urgency. Conclusion There are plenty of tools and consultants to help you get started. As your company grows, you will find yourself relying more on IT documentation, especially as more IT projects and infrastructure move to the cloud and outside the walls of the company. Understanding dependencies and licensing restrictions are two examples of when the lack of documentation can come back to bite in the form of broken applications and severe fines. You will need documentation one day, so why not get started now?