Editor’s Note: The following piece, by M. Katherine Brown, is part of our collection of “classics”–articles that stand the test of time no matter how many technologies come and go.
Mention team technical reviews to a group of tech writers and chances are good that you will either get a loud, collective groan, or the group will vie to tell the best review horror story. On the one hand, technical reviews are a vital part of our jobs because they help us to produce high quality product documents. On the other hand, technical reviews gone wrong are the bane of our existence. The good news is that we have the power to conduct consistently effective technical reviews. This article summarizes why we do reviews and what often goes wrong in reviews, and then summarizes steps to take before, during, and after technical reviews that can help you conduct effective team technical reviews. Although your process and team may differ from what’s described here, you can apply the information in part or in whole to improve your current review process.
Why We Do Reviews and Why Reviews Often Go Awry
As technical writers, we have important reasons for conducting technical reviews:
- Technical reviews can provide a system of checks-and-balances from a variety of Subject Matter Experts (SMEs) on the team, which helps bring technical accuracy and completeness to the documents we produce.
- Technical reviews can help improve the product’s design and catch problems or bugs, which can help improve both the product and the accompanying documents. And, as a result….
- Technical reviews can help reduce product development costs, minimize problems for product users, and help reduce technical support calls or needs.
Most people on the project team would agree with these reasons, but despite these common goals, technical reviews still go awry. What’s more, reviews can often go awry for a number of reasons at a number of points in the overall process:
- Poor communication
- Lack of preparation
- Lack of management support
- Unclear expectations and objectives for the review
- Insufficient time planned for the review
- Lack of follow-up
- Wrong people involved, or right people involved at the wrong time
As communication specialists, we can–and should–take steps to facilitate communication throughout the review process, which is the core of a successful review. As you’ll see in the following sections, conducting an effective team technical review requires commitment from the project team, management, and from yourself; however, with proactive communication, consistency, and organization throughout the process, the review process can indeed be effective.
Before the Meeting
Recognize that producing quality documentation is collaborative process that takes time and commitment
- Get involved early in the project. As the user advocate, you have a unique perspective on the usability of the product. Use your expertise to eliminate usability problems early in the design phase. For example, if you are working on a software product and the UI (User Interface) contains text that is idiomatic or jargony, you can provide alternatives early in the design phase.
- Obtain a commitment from managers to support the technical review process. Get to know the project managers and establish a rapport with them. Educate them about your needs, work with them to establish goals and roles, and work with them to establish consequences for team members being unprepared or for not participating as expected.
- Establish a rapport with the rest of the project team, too. If the team whines about review meetings, plan to take steps throughout the process to make reviews more pleasant by accommodating–as much as possible–their schedules, bringing food or drinks, or even offering prizes for the most issues found.
Identify the review team
- Work with the managers to recruit a cross-functional review team, with members that offer expertise from all areas of product, document, and business development.
- Know the key players. Typically, you want to include the functional leads at the review meeting. These leads are responsible for collecting comments from the other members of their functional group.
- Identify the secondary reviewers. Know which team members are the experts in which topics. These reviewers can also help review sections to help ensure accuracy before the official review process.
- Plan, as much as is possible, to have a consistent review team. Bringing new people into the review cycle in the middle of a project causes the review process to grind to a halt because the new person inevitably wants to rehash decisions made by the project team. If you must add a new reviewer during the project, take the time to provide them with the list of issues and solutions that have already been identified and responded to. This will help bring the new person up to speed, and will reduce their need to rehash issues.
Be prepared
- Develop a project plan and content plan. Have the team review the plans so that they know how your work meshes with the rest of the project schedule. Work with the project manager to incorporate your deliverable schedule with the rest of the project schedule.
- Use all of the resources available. As you’re developing product documents, use the design specifications, functional specifications, meeting notes, or other project documents as a starting point for answering your own questions. Get access to prototypes as soon as they’re available, and use them throughout the document development cycle. When approaching SMEs, ask informed questions, tell them what you’ve done to answer your own questions, and take time to understand an issue while you have an SME’s attention.
- Ask people in your immediate group to preview product documents before sending them to the project team. By doing so, you can often eliminate more obvious problems or ones that would detract from technical review goals. Then, incorporate needed changes and resolve any issues before sending the document to the project team.
Provide clear objectives and instructions for each review
- Educate the project team on what to review–and not review. Different stages of a project require a different focus, and team members should be informed of the goals and needs throughout each review pass.
- Clearly identify the document’s purpose, audience, and scope.
- Identify specific issues that need to be addressed in each review. For example, if the lead engineer needs to provide you with information on a particular section, indicate that you want her to pay particular attention to that section and specify what issues to look for.
- Establish sign-off protocols. Before the project begins, establish procedures for the required sign-off, and establish criteria that the document must meet at each review phase.
Provide sufficient time for the review
- Plan review time into the project schedule. If it’s not in the project team’s schedule, it won’t happen.
- Work with reviewers (individually and collectively) to find out what review schedule(s) would best meet their needs.
- Schedule the review meeting. Be specific about the time, place, and agenda, and provide a copy of document and any review instructions.
- Establish realistic deadlines for returning comments. Don’t expect a thorough review if you give the team a 30-page document at 3pm on Friday and schedule the review for 9am on Monday.
- Give reviewers at least 48 hours to review even a short document and a week for anything over 20 pages. Even though the documentation is your primary responsibility, it’s likely a secondary responsibility for other team members.
- Break large projects into manageable chunks. Unless it’s the final check on a document, provide reviewers with only a few chapters or sections at a time. Or in the case of online help, provide them with a set of related topics.
- Establish and announce a finite time for the meeting. Typically, people’s attention tends to wander after about two hours. Even if you aren’t finished with the review, end the meeting on time and schedule a new time to finish the review. If you are almost done and time is up, you can take a vote to see who wants to continue on.
During the Meeting
Assign someone else to be the review leaderThis person should be one who understands the purpose and goals of the review, who can push people along through the review, and who can guide people back on topic when they stray:
- Go page by page through the document to be reviewed. Pause for 15 seconds or so as each page is announced. If no one has a comment, move on.
- Keep discussions focused. Sometimes tangential issues arise during the discussion. In this case, acknowledge the issue, assign an action item, and arrange for the item to be resolved–either with an individual or at another meeting. During the meeting, though, stay focused on the topic at hand.
- Keep comments constructive. The comments should be about the documentation and what will improve it, not about someone’s personality flaws or competence.
Assign yourself as the recorderAs the person responsible for incorporating changes, you care more than anyone else on the team about how clear the comments and solutions are. By being the meeting recorder, you can focus on listening rather than talking, and you can ensure the notes about changes needed are clear for your needs:
- Use a review form. The form should contain space for the name of the document, the date, team signatures, and the issues list.
- Track both direct and indirect issues. Attach the form to the document; mark up the document with direct issues, and document indirect issues on the form.
- Assign action items to appropriate people. If an issue requires further action, assign someone to take care of it and give them a deadline. Then, follow up with a reminder after the meeting.
- Ensure that the appropriate people sign the review form after the meeting. The signatures give you a paper trail in case of problems. Save the forms, and make a backup in case problems arise after the project is completed.
Resolve direct issues in the meeting, if possible If the project team disagrees about how to present a piece of information, for example, discuss it and come to agreement about wording or presentation during the meeting. Determine whether or not another review is required If there are minimal changes, suggest that the leader check the changes and sign off, rather than convening another meeting. Make second reviews “changes only,” unless the document was significantly changed as a result of the first meeting This will keep the review process moving and prevent revisiting every issue every time.
After the Meeting
Follow up on action items and issues
- Send reminders about action items.
- Resolve issues promptly.
- Go over complex comments with the reviewer, if necessary, as quickly as possible after the meeting.
- If you don’t incorporate a particular comment, document the reason.
- Follow your document control procedures.
- Thank your reviewers for their time. This small courtesy will go a long way toward ensuring help on future projects. In addition, if someone was particularly helpful, you may want to further acknowledge their contributions with a special public thanks or a message to her boss.
Conclusion
With a bit of proactive communication, consistency, and organization, a team technical review can indeed be effective. In short, communicate, be prepared, be clear, and follow through. As a result, you can improve the accuracy and completeness of the documents you produce, improve the product itself, maximize users’ experience in using the product and documents, and reduce product development costs. Good luck! And, remember engineers will work for food.
