Project Documentation Essentials

October 23, 2017 Collaboration, Support, Trends

Documentation--1Today I wanted to discuss the importance of good documentation as well as what good documentation should include. I’m covering everything that we keep internally and provide to our clients as documentation. Documentation is important for a variety of reasons and to a variety of audiences. Customers typically receive documentation at the end of a project, but they aren’t the only users of documentation. Partners need good project documentation too as our support team needs good documentation to help our clients. Our presales team uses documentation as a starting point when working through new project designs and quotes. Our implementation team will also use documentation to help plan new projects. These audiences are all important, and have different needs. Because of that, there are a lot of components that documentation needs to cover.

The documentation we include varies depending on the type of project. For example, there is much more information when we add a completely new system than when we add a site to a system. Our standard documentation includes the following:  project document(s), passwords, design workbooks, call flow diagrams, licensing, readiness assessments, voice gateway configurations and configuration reports. I’ll address each of these individually.

We create project documents to summarize the important elements of a project. Typically, this is done with a single document. This includes an executive summary, critical settings information and usernames (not password). This document includes the information needed to access the systems, and high-level configuration information. This document does not include complete detail on configuration or settings. We have detailed reporting for that purpose. Combining this document with passwords provides needed system access. It also provides enough configuration information to understand the system design. This document acts as a record of the project, and a starting point for someone unfamiliar with the project.

Passwords are the next item. We take password security very seriously. Passwords can be provided two ways. We can provide the passwords onsite directly, or we can send the passwords securely to the customer. We also add the passwords to our secure password store for clients that wish us to do maintenance or ongoing project work. Some projects don’t include passwords. For example, in the case of a site addition, the passwords already exist. Knowing the passwords and having the project document will allow an engineer familiar with the technology begin working on the system.

If design workbooks are used in the project they are included with the documentation. We use design workbooks to input information into the system and to plan. The most common design workbook is the phone workbook. We use this to merge the username and extension with the system settings we design. Once that information is included in this spreadsheet, we use it to create individual files for bulk importing the data. This gives us a record of what was bulk imported into the system, and can be used in the future if a device needs to be recreated.

Call flow diagrams are used when the call flow is complex. We include information in the design document for basic auto attendant call flow and functionality. For complex call flows, that is not sufficient. Contact Center call flows can be many levels deep and can include complex steps. A Visio diagram of the flow is included with the project so that the call flow can be understood. This helps anyone dealing with the system after it is installed. Understanding a complex flow by looking at the programming alone can be difficult and time consuming. This provides a quick way to understand that flow.

Licensing is another element that is important. We include the licensing used on the project primarily as a hedge against licensing questions in the future. If the system is upgraded, or in a worst-case scenario rebuilt, it’s important to have the licensing available. In the case of upgrades, it is sometimes necessary to provide the licensing information back to the vendor. This can also be done by researching the original sale and providing that information, but that is time consuming. It’s even more time consuming if the original license was sold by another partner. Any partner doing work on your system should provide you this information.

Readiness assessments are very important. We provide detailed readiness assessments to validate design requirements and overall system architecture and customized for the project in question. This assessment includes all the checks we use to determine that the system is up and running normally. This helps us avoid any misses and provides the client a record of what was tested.

Voice gateway configurations are included with our other documents. We do this to record the complete configuration. This information is not captured by our other tools and is important in case a voice gateway fails or needs to be replaced. It also provides a record of the gateway at the time of installation in the event that changes are made later that causes issues.

Configuration reports are the last item we include. We have reporting software that captures nearly every element of the system configuration. This information is contained in html files, spreadsheets, and csv files. With this information, it would be possible to recreate the system if a backup failed, although it would be a tedious process. Backups are a critical element of maintenance. This report also puts information in an easy to read format and shows associated information together. This makes the information easier to read than the individual configuration elements in the system.

We sometimes include other customized information depending on the project, but those are the highlights. It is very important that anyone working on your system provides this level of documentation. You may not read through it all, because there is a huge amount of data. You will be interested in some elements of the information and partners working alongside you will be interested in other elements. Not having this information can cause real headaches in the future and can cost a lot of time and money to resolve. Never accept documentation that doesn’t include a good project document at the very least!



Curtis brings over 25 years of collaboration experience to ABS. As the Collaboration Team Manager, Curtis works to ensure that ABS is consistently providing the latest collaboration technology and support to ABS clients.