Documentation

Projects that deliver software systems or other systems which require some degree of proficiency of the system's users must consider developing that proficiency as a project deliverable. Depending on the complexity of the system and the existing level of proficiency in the user community the proficiency may have to be delivered by training or a good User Manual or User Guide may be sufficient. The User Manual or User Guide delivered with the system should not be treated any differently than the other components of the system; quality standards should be established for the documents and the team should ensure that the documents developed meet these standards.

There is another source of documentation for the project: User Manuals or Guides that are part of system components purchased from a vendor. The User Manuals or Guides are an important part of the product and care should be taken in choosing a component with quality documentation.

Documentation is important to your project because it explains how to use the system, or components of the system properly. In the case of a purchased system component, the project team members directed to integrate the component with the new system, or with using the software to build the new system, will only perform their work proficiently if the information they receive in User Manual is well written. Even when team members can use the component without referring to the Manual, the Manual may contain information that would allow them to perform their work more efficiently. To derive this benefit from the Manual it must be well written. The user community who will use the system your project is developing will experience a similar benefit from documentation. They rely on these documents to tell them how to use the system properly to do their jobs. The manual is an important part of the education process even when users receive training. To do this job properly, the documentation you develop must be well written.

Purchased Software or Components

Documentation should form a part of your decision making criteria when selecting the best components or software to purchase. There are many different approaches when selecting a vendor (if you are unfamiliar with this activity, read up on your PMBOK® or review your PMP® Exam Preparation training), but the one that I'm most comfortable with is the criteria matrix. The criteria matrix simply lists all the criteria you will use to compare products and vendors, the scores each of the product/vendor combinations get in each criteria and the ranking of the criteria. The vendor who gets the highest score usually gets the sale.

Include the documentation that accompanies the product in the criteria you will use for ranking. Don't automatically rank documentation at the low end of your priority scale. Documentation may be an important part of the product, depending on its complexity, ease of use, and who will be using it. The wider its use and the more complex it is, the more important the documentation will be. There is no point in purchasing the best software or component available if your team or user community can't use it!

Some other considerations when assigning a priority to documentation:

• Who will be using it? Are they sophisticated users or novices?
• How widely will the component be used? Are there only a handful of users (e.g. a project sub team) or will the component be used company- wide?
• How mission critical is the component? If failure to use the component properly would cause a catastrophic failure, the priority should go up.
• How often will the component be used? How long will it be used?

Answering these questions will help you to prioritize the documentation realistically.

Scoring the documentation is a more difficult question. You are probably the last person who should do the scoring because you are highly unlikely to have to use the User Manual! The people in your organization who will be using it, should be the ones to score it. The first consideration is having a copy of the documentation available for evaluation. Ensure that a copy accompanies any evaluation copies of the software/component you receive for evaluation. The next consideration is the quality of the documents. Are they clear? Unambiguous? Well organized? Are they well written? Free of spelling and grammar errors? Is there an index? A glossary? These are just some of the things to be considered when evaluating documentation.

It is a good idea to have actual users evaluate both the component, or software, and the documentation. You usually won't be able to get the entire user community involved in product evaluations but try for a representative from each of the user groups. You may have to settle for one representative from the user community. If that's the case, make sure that evaluator is the least proficient, or most demanding person available. You should do as much of the evaluation work as possible. For example, your expert user community do not need to check the manual for spelling, grammar, indices, etc., these things are well within your ability to verify.

Schedule these evaluations and assign people to perform the User Manual evaluation. Planning this activity well in advance and communicating task assignments to the team will increase your chances of having the work done.

Project Produced Documentation

Project produced documentation is the other side of the equation. Just as we evaluate products we consider purchasing based on the documentation that comes with them, so others will evaluate our products based on the quality of our documentation. This logic applies even when your customers are your own user community. A great system accompanied by poor documentation will be perceived as a poor system by customers. Customers forced to accept the poor product will be resentful and resist taking delivery.

How do you ensure that your documentation meets quality standards? Establish those standards in much the same way you established them for your product evaluation. Here are some criteria you may want to use as standards:

• Is the document written clearly, concisely, and in good English?
• Does the document address all the different uses the system will be put to?
• Is the document free from spelling or grammar errors?
• Does the document have an index (if it needs one)? A table of contents? a table of figures? A glossary?
• Is the document easy to navigate? Can users find the information they seek quickly and easily?

By now it will become apparent to any readers who belong to the technical writers brotherhood that I am no expert in technical writing. This brings me to my next point: hiring technical writers to write your User Manuals or User Guides will serve 2 purposes, it frees up the BA or programmer who otherwise might have been tasked with writing the manual and it ensures a well written document. If the engagement of a technical writer as a contract resource or full time employee is beyond your project's budget, make certain that the person you do choose to do the writing is the most experienced document writer available. People who are used to writing specifications that others must interpret are one example.

Create your documentation from specifications the same way your create your system. Specifications in this case don't have to do with features or functions, rather they are directions on what should appear in the document, how it should be organized, etc. For example, you may want to specify that the document include a screen shot of any user facing screens as illustrations. The specifications may be part of a Functional Specification or Software System Specification, or it may be a stand-alone document. Normally, documentation standards will be the same across all applications, features, and functions and only the content will change. Document features that draw on information across the entire document should be accounted for. Assign someone on the team to compile the Table of Contents, Indices, Table of Figures, Glossary, etc.

Evaluating the written document against the established criteria/specifications is the job of the Quality Assurance group, or the group in your organization who perform this function. Testers should have to rely on the User Manual to guide their exercise of the new system. If your documentation won't be ready in time to QA test then ensure that it receives a User Acceptance Test before implementation. Users performing this testing should be given a copy of the User Manual to educate them on how to properly exercise the system. This approach to testing has 2 benefits: it will make testing more efficient and it will eliminate mistakes due to a lack of proficiency with the new system.

Final Words

Don't forget the support staff when evaluating purchased software or components and don't forget them when planning your User Acceptance Testing. It is vital that these folks become proficient with the system they will be supporting. Don't treat your system's documentation as the "poor relation" deliverable. Ensure that proper quality standards are established and communicated, then verify that the documentation meets those standards. Make certain that each user in the user community has a copy of the User Manual when the new system is deployed. You can't force users to read the manual but you can make it available and make them aware of it. Finally, don't put the User Manual on a shelf and forget about it. The system you just deployed will probably be around for some time, if it's a good system, and be updated frequently. Make certain that the User Manual is updated whenever there is a new release of the system which adds/deletes/changes features or functions. The same quality standards should be applied to the document updates as was used when the original document was written.