by Donn Le Vie, Jr.

You know the drill. You develop documents. You send them out for review. Maybe you also include a cover page that details what reviewers should focus on and offers examples of how to (and not to) provide comments. Maybe you ask reviewers to return comments to you. Or maybe you hold the dreaded (play bad horror-movie music here)...team document review. For many of us, a root canal sounds like a more fun and productive afternoon agenda....

While many potential problems plague us in getting the feedback we need for developing, improving, and correcting the documents we develop, a few problems stand out to varying degrees (and often across projects), depending on the particular review process used:

• Reviewers don't always know how to examine documents critically or how to identify specific problems
  
• Reviewers and other team members aren't always held accountable for providing feedback at all or for helping find suitable solutions
  
• Review processes don't always provide for a well-rounded review team that can examine documents from a range of perspectives
  
• Review processes often don't provide for examining root causes of the problems, which can help us pinpoint appropriate solutions and avoid similar problems in future documents
  
• Review processes don't often provide for accountability in implementing solutions
  
• Feedback from multiple reviewers, depending on the review process, can be overwhelming to translate into specific solutions and incorporate into document revisions
  

Time and again, we may not receive feedback on our documents that identifies specific problems, may not have an opportunity to identify causes of those problems, and may not have the needed support to implement solutions. In short, our documents are not always as thoroughly reviewed as we strive for them to be; root causes of problems are not adequately identified, if at all; and solutions are not always as efficient as they could be and often do not address real causes of problems.

In this article, I describe the document inspection method, which is a structured document review approach that we as technical writers can apply to practically any type of document, including documentation, reference materials, and product specifications, among other possibilities. Often used as a supplement to other review methods, the document inspection method can help us identify problems in documents, examine root causes of problems, find appropriate solutions, allow for realistic review schedules, and make reviewers accountable for providing input and implementing appropriate solutions. In this article, you'll see how the document inspection method works, see why it can improve review results, and see when and how to apply the method to your own situations.

Understanding the Document Inspection Method

You might think of the document inspection method as an individual-based team approach, where inspectors are part of an inspection team but do most of the work individually. The method is based on the idea that each inspector has assigned responsibilities, uses pre-determined inspection criteria, and develops an inspection log that ranks problems according to their severity. This methodical approach can often provide more usable feedback and information to writers because it assigns responsibility, draws on team members' expertise, lets each member focus on a specific area, and ensures that a range of perspectives and expertise contribute to document improvements. And, as you'll see, the method helps teams identify not just problems and solutions, but also root causes of the problems, which can help teams better identify appropriate solutions and prevent similar problems from occurring in future projects.

The document inspection method begins with an inspection team that includes representatives from all areas of the product and document teams who contributed to the particular document (usually a chapter or section from a manual) under inspection. This team could include the writer(s) or editor, someone from Quality Assurance, applications engineer(s), programmer(s), and so on. Ideally, you'd also include customers or end users in the inspection process. The specific individuals who comprise the document inspection team may change, but the functional roles are consistent from one document inspection to the next.

The diversity of the inspection team is a key part of why the method can be successful in meeting review goals. By assembling a diverse team and then assigning each inspector specific responsibilities that draw on the individual's expertise, you can find problems and implement solutions on all aspects of the document. Compared to other team-based approaches, the inspection method can provide a better feel for the document's content, accuracy, reliability, completeness, and so on, as Figures 1 and 2 show.

As you'll see in the next section, the cornerstone of the inspection method is what's called a defect inspection log, which is a form or spreadsheet that inspectors use to identify and rank problems found in documents. In addition to providing information that specifies the project, chapter, or section being reviewed, the inspector's name, and similar information, the defect log provides a common format for inspectors to identify page numbers, line numbers, defect rank, and additional notes, as Figure 3 shows. The key point to remember about defect logs is that they are used to objectively track defects in the document and do not (and should not) focus on the writing ability or style of the document author. For example, a "style" defect should relate to how an item does not conform to a standard in your organization's style guide.

Understanding the Inspection Process

The inspection method includes five steps:

1. Prepare the documents
   
2. Hold a kickoff meeting
   
3. Prepare the defect log
   
4. Hold a post-inspection meeting
   
5. Hold a corrective action meeting
   

Step 1: Prepare the Documents

You (or the person identified as the facilitator) begin the inspection process by planning for inspectors' needs and ensuring the documents are ready, available, and up to date:

<Note The document being inspected must be tied back to a parent document, which can be a requirements-definition specification or a documentation project plan, for example. By doing so, you can help ensure that the documentation and software/product develop in a parallel manner, help prevent the project from expanding beyond the original scope as defined in the parent document, and have point of reference for comparing document drafts as the project progresses.

• Is the document ready to be inspected? A document can be distributed for inspection at any time and more than once, if necessary. Your documentation team should work with the product development team and the QA team to determine when a document inspection should occur; however, in general, an inspection isn't called for until a document has already been through a first draft editorial pass. You should prepare the document for inspection by adding line numbers to the margins (a feature available in most document development software) and including the document version number and page numbers in the footer. By doing so, you provide inspectors with common references that they can use throughout the entire inspection process.
  
• Is other supplemental information ready? In addition to preparing the document, you should also prepare (or update) a copy of the standards used to inspect the document, as well as a list of some common problems to look for. Ideally, the editorial standards used for the inspection should be derived from your organization's style guide. The code or engineering standards used for the inspection should be derived from your organization's software or product development methodology. You want to create an inspection process that improves with each use; therefore, without a set of baseline standards to start with, it's difficult for a document inspection to yield optimum results. Table 1 shows a sample of Inspection Standards and Common Errors list for documents.
  

Table 1 As shown in these examples, Inspection Standards and Common Errors Lists can help keep feedback consistent and simplify identifying root causes of defects.

Inspection Standards for Documents

Common Errors for Documents

Should be no longer than one page. Assigned owner to keep standards current. Criteria: Must be written to reader's level (as defined in the parent document) Must be have been spell-checked All tables and figures must be referenced in text Must provide contact information for additional assistance Must have an index and glossary All acronyms must be defined at first mention in each document being inspected Must have a revision level and date in footer Must state level of confidentiality in footer (confidential, secret, etc.)

Should be no longer than one page. Assigned owner to keep standards current. Criteria: Spelling errors Punctuation errors Incorrect grammar Table/figure not labeled Acronym not defined at first mention Improper style use No revision date or number Improper use of trademarks Incorrect use of template paragraph tags Missing glossary or index Figure/table not referenced in text

With such documents in hand, inspectors have the information they need to begin examining the document for problems. These supplemental documents are, of course, working documents and should be examined and refined by both you and the inspectors throughout the process. Each inspector will have an Inspection Standards sheet and a Common Errors sheet that are particular to their technical specialty, all of which tie back to the parent document.

Step 2: Hold a Kickoff Meeting

With the documents prepared, the next step is to hold a kick-off meeting, which is a planning meeting of sorts, where expectations, roles, and responsibilities are defined, and the supplemental lists are distributed. This meeting doesn't have to be formal or necessarily long (five to 30 minutes is common), but it should accomplish some specific goals:

• Define and classify defects according to their severity, such as being Low, Moderate, High, Questions; or 3, 2, 1, Q. For example, the definitions might look like this:
  
  • High (1): Could jeopardize the project success. This defect will cost time if not caught during this stage. Incorrect and missing content are examples.
    
  • Moderate (2): Problem that requires correction before proceeding. It could create customer confusion. Ambiguous content and missing illustrations are examples.
    
  • Low (3): Mostly cosmetic or style problem. Grammar and punctuation errors are examples.
    
  • Question (Q): Requires a clarification or additional information needed from the writer or Subject Matter Expert.
  
  
• Determine the amount of time inspectors will work on the inspection, which helps ensure that defect logs include a consistent level of inspection from each person. The elapsed inspection time helps determine the degree of "completeness" of the technical content for that draft (for documents). That is, if statistics show that it takes two hours to inspect 12 document pages, and you've already spent one hour on four pages, the technical content may not be sufficiently developed for an inspection. If an inspector needs three hours to inspect 500 lines of code when it should require only two hours, there may be a problem with the code (e.g., too much commenting or too many iterative loops).
  
• Determine information and details to note in the defect inspection log. Using the standards lists and other supplemental documents provided as guidelines, inspectors might look for these problems, for example, among many other possibilities depending on the document and product:
  
  • An incorrect or missing statement
    
  • Repeated occurrence of an error
    
  • Deviation from standards
    
  • Ambiguous content
    
  • Missing graphics/tables (or not referenced in the document)
    
  • Undefined acronyms, abbreviations, and initialisms
    
  • Problems in design or programming
    
  
  
• Ensure inspectors have the correct version of the documents.
  
• Assign perspectives and inspection responsibilities. That is, an inspector might be assigned to examine the code based on her expertise, while another may be assigned to examine the software architecture.
  
• Assign a meeting moderator, who is responsible for keeping subsequent meetings on track and moving forward
  

Step 3: Prepare the Defect Log

During this stage, each inspector works alone to evaluate the document using the assigned perspective, note any problems in the log, and comment on the nature of the defect using the Standards sheet or Common Error sheet as guides. When inspectors have completed their defect log, they forward it to the meeting moderator.

Step 4: Hold a Post-inspection Meeting

After the inspectors have completed their assigned defect logs and forwarded them to the meeting moderator, the inspection team meets again and discusses the problems that each inspector noted. At this point, the team does not discuss solutions or assign who will take care of what problem, but instead aims to make the team aware of the problems and, throughout discussions, may discover new problems. Again here, this meeting doesn't have to be extensive or long; however, depending on the problems found, it can go on for up to two hours or so (a two-hour time limit should be ample).

Step 5: Hold a Corrective Action Meeting

Depending on the length of the post-inspection meeting, this next meeting can be held as part of that meeting or as a separate meeting within the same week or so. You might think of the Corrective Action meeting as being a brainstorming meeting of sorts with three purposes:

• The team determines the root cause(s) of the top three to five most common or most expensive problems found in each area, and prioritizes them for each area. By brainstorming the various ways these most common or costly defects occurred and ways they can be prevented, the team can begin to explore those solutions first.
  
• The team examines the root causes of those problems, which can help improve inspection standards, error lists, and processes for future projects.
  
• The team assigns the corrective actions to individuals; every corrective action is assigned an owner and completion date.

Applying the Document Inspection Method

As described throughout this article, the document inspection method can help us to identify, track, and correct defects in document drafts, and to assign accountability to all participants in the inspection (and ultimately, the resolution) process. And, as far as helping improve and manage team document reviews, this method can help us to do the following:

• Show reviewers how to examine documents and identify specific problem areas
  
• Provide for a range of perspectives to ensure content integrity, clarity, accuracy, and absence of ambiguity
  
• Provide a unified, structured way of presenting feedback to document authors
  
• Provide a way to analyze root causes of problems that leads to workable solutions
  
• Hold reviewers accountable for moving the process forward
  

Although the inspection method can reliably help meet these goals, it is not suitable for all project review needs. In particular, this method is less suitable for reviews that aim to collaboratively brainstorm, walk through procedures, educate team members, or assess overall progress. In these cases, other review approaches, such as walkthroughs, technical reviews, peer reviews, or management reviews, would likely be a better solution.

Is the inspection method suitable for your documentation organization? Are you experiencing problems with review accountability, inadequate or myopic feedback, and one-dimensional perspectives? Are you frustrated by the lack of substantive solutions to content problems? If so, then the document inspection method might be a good solution to explore. While I've provided some very specific information, the nuances of this process aren't carved in stone, which means you can adapt it to suit your organization's needs. Additionally, this method would often be used to complement--not necessarily replace--other document review methods.

Your first step would be to meet with the product development and QA project managers to determine your specific strategy based on the ideas presented in this article. In exploring adopting this method, consider the following:

• The process must be coordinated with other departments and tied back to a parent document (you may have to generate the parent document if it doesn't exist).
  
• The inspectors are also responsible for keeping current the Standards sheet and the Common Errors sheet, which may add to their overall responsibilities.
  
• Scheduling Kickoff meetings and Post-Inspection/Corrective Action meetings can be difficult with people in different geographic locations and times zones, as well as with people who travel frequently.
  
• The entire document inspection process can require more time than the team-based document review method, particularly with team members scattered about the globe and in various time zones.
  
• Getting programmers away from writing code or getting engineers away from engineering to attend the various meetings can be a difficult task, unless your company fully embraces a bona fide software/product development methodology that mandates accountability and participation in the document review process.
  

Conclusion

As technical writers, we face a number of potential challenges in having documents reviewed. The document inspection method can help us overcome these challenges and can be an excellent tool for helping identify problems and errors in the documents we produce. As discussed throughout this article, the inspection method can often provide more usable feedback and information to writers because it assigns responsibility, draws on team members' expertise, lets each member focus on a specific area, and ensures that a range of perspectives and expertise contribute to document improvements. Further, the method helps teams identify not just problems and solutions, but also root causes of the problems, which can help teams better identify appropriate solutions and prevent similar problems from occurring in future projects. As a result, we can receive useful, consistent feedback on our documents, have the support to improve documents and processes, and make our documents even more usable for our readers. And perhaps better yet: the team document review process won't be so dreaded....

Donn Le Vie, Jr., president of i2d2, is an information design and development consultant and author. He has written two nonfiction books, 60 technical articles, and more than 700 general-interest articles. Donn's latest book, Designing Killer eCommerce Proposals that Win New Business, will be available in 2001. His two books in progress, Watch Out for That Man Eating Shark, and When the Programmer Bursts Across the Partition are commentaries on technology, communication, and human factors. You can reach Donn at dlevie@austin.rr.com [1].

Figure 1 Traditional team-based approaches often don't draw on enough perspectives, resulting in reviews that do not address all aspects of a document.

Figure 2 The inspection method, which draws on a variety of perspectives and expertise, offers a more comprehensive document review.

Figure 3 The Defect Inspection log lets inspectors identify and rank problems in a consistent format.

Writing and Editing [1]

• Reviews [1]