Creating process documentation may be an unappealing task for IT, but it's a very important one. The quality of your documentation can affect how often a process is used. How does yours measure up?
By Rich Schiesser
IT professionals’ duties sometimes include a number of unappealing tasks: late-night calls, last-minute changes to test schedules, unreasonable customer requests, and weekend upgrades. These annoyances can pale in comparison, however, to process documentation, the scourge of infrastructure management. You’ve just spent months planning, testing, and implementing this process. Now the client wants you to document it as well?
This reluctance to document is understandable. Highly knowledgeable IT personnel usually excel in technical skills more so than in writing. Some view writing as a less important, peripheral part of their jobs, or as a task that is simply beneath them. Many IT pros struggle with how to determine the true quality and value of the documentation they’re generating. Here’s how IT analysts can effectively make these determinations and, in the process, transform a potential scourge into a blessing.
Evaluating process documentation
Many shops develop excellent processes but fail to document them adequately. After an initially successful implementation, procedures are unused due to lack of documentation. This is particularly true in the case of new staff members who are unfamiliar with existing processes.
Some documentation is usually better than none at all, but adding value and quality to documentation increases the likelihood that the process it describes will be properly used. But what makes for good documentation? Evaluating the quality of documentation is largely subjective, since few techniques exist to objectively quantify the quality and value of process documentation. Here’s an approach I’ve developed over several years while working with many clients.
Quality of content
The purpose of evaluating content’s quality is to show to what degree the material is suitable for use. The purpose of evaluating its value is to show how important the documentation is to the support of the process and how important the process is to the business. Documentation’s quality is evaluated with 10 common characteristics of usability. Each of these is described in Figure A.
This set of 10 characteristics is designed to cover a broad spectrum of quality attributes applicable to a wide variety of documentation types.
Our evaluation system next looks at the documentation’s value to your business using five common characteristics:
- Critical nature of the process—How vital is the process described by this documentation to the successful business of the company?
- Frequency of use—How frequently is the documentation used or referenced?
- Number of users—How large is the potential user group for the documentation?
- Variety of users—What are the different functional areas or skill levels of personnel who will likely use this documentation?
- Impact of nonuse—What harm is likely if the documentation is not used properly or not used at all?
Each characteristic for both quality and value can be rated on a scale of 0 to 3, with 3 denoting that all aspects of the characteristic have been met. The maximum quality rating for any piece evaluated is 30, and the maximum value rating is 15.
Benefits of the methodology
This method of documentation evaluation has three major benefits. The first is that it gives a snapshot of the quality of existing documentation—particularly documentation of high value—at a certain point in time. If documentation improvements result in new ratings, they can be compared to a previous rating.
The method’s second benefit is that it enables you to customize your criteria for quality and value of documentation to reflect changes in priority, strategy, or direction. In this way, the methodology remains applicable regardless of the specific criteria used.
The third benefit of this method is that it allows comparisons between different types of processes within an infrastructure using the same standard of measure.
Once both the quality and value characteristics are evaluated, the two sets of attributes can be shown on a quality/value matrix, as shown in Figure B. Quality ratings are shown along the horizontal axis, increasing to the right from 0 to 30. Value ratings are shown along the vertical axis, increasing as it ascends from 0 to 15. Each axis is scaled from the lowest quality and value ratings up to the maximum possible. The matrix depicts both the value and quality of each piece of documentation on a single chart.
The matrix is then divided into four quadrants. Points in the upper-right quadrant (1) represent documentation that is both high in value and high in quality. This is the desired target and constitutes excellent documentation that requires little or no improvements and only periodic reviews to ensure continued high quality. Points in the lower-right quadrant (2) signify material that is high in quality but lower in value to a particular infrastructure. Documentation in this area is generally rated as good, but it can be improved.
The lower-left quadrant (3) represents documentation that is relatively low in both value and quality. Material in this area is designated as only fair and in need of improvement. Because value is low, improvements are suggested on an as-time-permits basis. Points in the upper-left quadrant (4) indicate documentation that is high in value but low in quality. Documentation in this area is considered to be at the greatest risk since it represents material that’s particularly important to the organization but is of poor quality. Obviously, documentation in this quadrant should be improved as soon as possible to prevent damage to processes, procedures, and services.
Our matrix’s ability to instantly identify documentation that needs to be addressed most urgently makes the rating method a potentially powerful tool. Both managers and analysts benefit from this identification. Rather than issuing a blanket statement that large amounts of documentation need to be generated, managers can direct analysts to initially concentrate on those pieces that have the lowest quality and highest value to the company. This method of evaluating the quality and value of documentation can make the task of improving it more appealing to IT analysts and less of a headache.
For more information on the Harris Kern Enterprise Computing Institute, visit www.harriskern.com/.