Best Practice Guidelines for Documentation

Documentation can be one of the most difficult parts of a project. You might find it is difficult to get your team to spend the time required to get the documentation completed. Having an effective strategy to keep your documentation effort useful, efficient, and done on time will help you keep your project on time and focused on long-term results.

According to general best practices you should focus on:

• Branding – Don’t be afraid to create a standard template so all your relevant documents have the same general appearance and sections. This should include a table of contents, page numbers, and corporate logos. This will also give the documents an “official” appearance which can help sell the idea that everyone should be reading and following procedures in the documents.
• Schedule Time – Effective documentation doesn’t just happen, you have to schedule the time for the team to create the documents. Put the time on your calendar and force the team to spend the time required to write good documentation. There should also be periodic scheduled times on your calendar for allow you time to review existing documents and determine the required updates to keep the existing knowledge base useful.
• Include Details – Write as detailed documentation as you think you will need, and summarize the data in a second version of the document if you need an executive summary. You need to determine the right level of documentation for your audience, but details are usually only available during the project and fade over time unless they are written down. Things that seem obvious today will be lost to time if they aren’t written down for future audiences.
• Location, Location, Location – Good documentation will only be read if it can be found. Documentation is worthless if no one can find it when they need it, so make sure it can be easily located. Make sure the proper infrastructure is in place to help users access the documentation.
• Knowledge Sharing – People generally don’t like writing documentation but find good documentation very useful. Make sure you put your documentation in a place where the people who need to read it can get to it without any issues. You might create different types of documentation (printed, electronic, Wiki, video, etc.) based on the target audience.
• Up-to-Date – Keeping documentation current is one of the hardest thing for people to do well. Selling your team on the need to create the original version will be difficult enough, but asking them to review the documentation months or years later will be a hard sell, especially if the team already feels overworked with other projects. Using a version control will help you to manage the various versions of the documentation so you keep the latest version available and backed up.