Barriers and Approaches to Reviewing Documentation |
Editor's note: This is the first of a two-part article on implementing a software documentation review process. The second part is scheduled to appear in the May/Jun issue of the Boston Broadside.
This article discusses some important issues in implementing a software documentation review process. If you are part of a small development organization and have few reviewer resources available, you may have to improvise techniques for providing the services and procedures suggested here.
However, regardless of the size of your organization, don't shortcut your planning. Good planning and focus are important and essential elements for effective, well-directed documentation reviews and, therefore, to the success of your project.
A successful review process is essential in developing accurate and useful documentation and instructional materials. The document review is a content check of an entire document by one or more reviewers. It focuses on the clarity and completeness of the technical content, as well as the grammar, punctuation, and formatting of the document.
Implementing technical edits, updates, revisions, and rewrites is the responsibility of the writer and may be negotiated with the reviewer. Issues concerning system functionality and accuracy of information should be addressed during the quality analysis and review process. Matters concerning documentation priorities, scheduling, and format standards should be brought to the attention of the documentation or technical publications manager.
The dynamics of a review vary according to the type of material being reviewed. When reviewing product documentation, your reviewers comment on the technical and editorial precision of your documentation, thereby helping you create documentation that best describes how to effectively use the product. On-line tutorials need to be reviewed and tested on the screen. Help systems can be reviewed on hard copy representations of screens, but it is best to review and test these on-screen. User manuals and reference cards are traditionally reviewed on hard copy drafts but, if carefully planned, they can be distributed to reviewers as electronic files.
Project Team Reviewers - These reviewers are members of your project or product team. They often include product managers, developers, technical or customer support staff, product management staff, and software testers. These reviewers ensure that the vocabulary, style, and substance of your documentation is appropriate for the intended audience. They check to determine that a user can clearly understand how to run examples, if necessary. They also check that all necessary and pertinent information is included or cross-referenced when it appears elsewhere.
General Reviewers - These are reviewers who may not be members of your project or product team. The may be selected from the general pool of product and technical expertise existing in your organization. They could include contributing developers, technical support staff, QAstaff, technical field support staff, and product management or marketing staff.
These reviewers ensure that your documentation fully describes the features and functionality of the software, hardware, services, or products. They check that text, examples, and product pictures are current, technically correct, and useful. They also check any version or system-specific information that may be missing. To assist the reviewer, you can include questions and annotations in your draft, use on-line bookmarks, or highlight important sections of text or pages for close scrutiny.
Editorial Reviewers - These reviewers could include anyone who accepts your invitation to review your document, or anyone requesting to check and review your document. Generally, they ensure that your documentation is understandable, usable, and well-organized. They check the format, text, and terminology for consistency and adherence to acceptable style standards.
Customer Reviewers - These reviewers include individuals from field test sites, beta sites, field and training staff. They use the documentation for reference work, product evaluation, initial training, and pre-release testing. They occasionally read and comment on new sections of the documentation. Information in the documentation is also used by those who unpack, distribute, and install the products.
Peer Reviewers - Before your work goes out for an informal or formal review, have another writer in your group look at it. Writers can inspect a document for errors, omissions,and deviations from department standards and conventions. They can give you early confirmation that your draft is sound and fits into overall documentation planning and strategy.
In a more practical sense, the peer reviewer gives you the benefit of experienced input as you describe the use of a new product to the various members of a project team or development group. That input may focus on document structure, intended audience, use of conventions, and use of textual and visual aids. The peer reviewer occupies an excellent position to offer valuable improvements to clarity, consistency, and brevity and can also provide constructive feedback in a non-arbitrary, face-to-face manner.
Informal Reviews - Generally, these reviewers see the draft often before a mutually satisfactory iteration appears. Then, they review your material for final, or last minute, check and release. They are informal because the information is checked on a section-by-section basis where a project leader, for example, scans a section just to see if it's "on the right track."
Editors and product developers are good informal reviewers. If your text is readable and reflects your knowledge with the product, you are less likely to solicit superfluous remarks from other reviewers. If these reviews go well, the formal review can be a breeze.
How often you pass your work back and forth among informal reviewers depends on your schedule, your reviewers' schedules, and your patience. You should not cling zealously to drafts until the perfect iteration appears. Also, it is best to limit the amount of "hot off the press" information your reviewers must see (perhaps no more than three rounds, but, above all, avoid multi-draft pinball).
It is a good policy to check the style, voice, and readability of the document before your reviewer sees it. It is helpful to give your reviewers specific instructions and information for the review being requested. You can also provide an outline of all sections you submit so a reviewer can quickly assess the overall organization and progress of the document. Finally, you may need to request the reviewer use reasonably legible penmanship to avoid interruptions trying to decipher written comments.
Formal Reviews - Formal reviews are specified by the documentation schedule. They are formal because they involve designated individuals from different departments and are usually performed on complete drafts. Formal reviews usually occur after you have completed a first draft and can continue until the sign-off of a final draft.
Field Test Reviews - Usually, during testing, your documentation may be sent out for actual use by customers, or prospective customers, and to sites within the company. Review feedback from the field is exceedingly valuable at this time. Be sure to save a copy for your files and, perhaps, a protection copy to be used as a master for tracking any edits that come back from the field testing or noted on a final test report. Maintain a record of the names and contact information of the off-site reviewers.
Preparing for Review - By the time the formal review date arrives, your draft may have been checked several times, perhaps by a colleague, editor, project leader, and developer. Before you circulate your copies, attach a distribution cover sheet to each copy. Your objective at this time is to keep your documentation from getting buried under a stack of paper on someone's desk. Ahand delivery to people on the distribution list is a friendly and useful way of introducing your work and yourself to a reviewer who is infrequently contacted. Make sure you include vital information about the review:
Generally, your cover sheet should explain whatever is necessary to ensure that your documentation draft is read and understood in its correct context. If reviewers inform you that they cannot read the whole text, then request they read and comment on those areas they know best. You might remind the reviewer to please don't ask you "Is this the way it works?" or "Are you sure?" As far as you know, the information is correct. You might use a highlighter to mark any sections to which you want the reviewer to pay particular attention. If the reviewer disagrees with something in your draft, the reviewer ought to test it against the product and offer a correction or recommendation to correct it.
Technical Luncheon - Many reviewers are not sure what they are looking for when they receive a document to review. Hold a technical luncheon on reviewing documents. A possible title could be, "How to Review a Technical Document: It Won't Be Freshman Composition." Include in your presentation what you expect reviewers to do with a review draft, how you want them to respond to you, and how they become part of the product development process for documentation. Draw upon the participation of people who have been successful reviewers in previous documentation projects.
While planning the luncheon, arrange for a "press leak" to let the word out that refreshments are available. Once the event is under way, show a "demo" of a very simple process, such as how to use on-line annotations and bookmarks. Conclude the meeting with a summary of the most important suggestions and ideas discussed. Follow up by thanking the participants for attending.
The Review Meeting - Receiving comments by paper and/or electronic mail, or handling questions and comments by phone may not always be adequate. Network problems may exist. Resources are limited and reviewers don't always have sufficient time to read and comment on your draft. Your time is also valuable; tracking down the reviewers individually to resolve questions may not be the best use of your time. Your project may have a history of software or documentation problems and you are part of the get-well plan. It may become necessary to gather your reviewers in a conference room and conduct a review meeting.
The purpose of the review meeting may be to resolve disputes between reviewers, clarify problems, or conduct a document walk-through. The meeting should be organized, staffed, and conducted with the reviewers whose participation most directly affect the success of your project. Once you select the attendees, agree on a date, time, place, and ground rules (e.g., review the documentation, not the promotional literature). The review meeting can provide your reviewers with the opportunity to pose "heads-up" questions or give you immediate feedback and answers to unanswered questions.
Jason D. Traiger is documentation manager at Kurzweil Applied Intelligence in Waltham.