|
–Geoff-Hart.com: Editing, Writing, and Translation —Home —Services —Books —Articles —Resources —Fiction —Contact me —Français |
You are here: Articles --> 2001 --> Inspiring reviewers to review your documents
Vous êtes ici : Essais --> 2001 --> Inspiring reviewers to review your documents
by Geoff Hart
Previously published as: Hart, G. J. 2001. Inspiring reviewers to review your documents. <http://techwhirl.com/columns/inspiring-reviewers-to-review-your-tech-writing-documents/>
Even the most skillful technical writers face the task of persuading Subject Matter Experts ("SMEs") to review our documentation for technical correctness; after all, they're the experts, not us. If pressed, even the most reluctant SMEs acknowledge the value of these reviews. For example, where the interface is in a state of flux, you may have documented something that's changed since you last saw it, or may simply have misinterpreted something that seemed perfectly clear to the person who developed it—and to nobody else. But reviews still take them away from their regular work. And when they're working overtime to meet a deadline—which is often the case in today's "hurry up" world—they find that additional work particularly intrusive and unwelcome. Being only human, rumors to the contrary notwithstanding, they'll seek ways to avoid the extra work or to focus on easier targets than technical checks—such as your writing style. Worse still, carefully reviewing the copious documentation generated by complex products requires concentration and dedication that reviewers may simply be unable to provide.
The bottom line? To obtain good reviews, you must make the process as painless as possible for reviewers. Here's how:
Management's attitude toward reviews determines whether you're going to succeed. Managers who consider reviews an unnecessary burden and who provide no support for the process can make good reviews next to impossible to obtain, particularly if their staff learn that shoddy reviews carry no consequences. Conversely, managers who encourage conscientious reviews by budgeting review time in the development schedule and making the quality of reviews part of an SME's evaluation encourage high-quality reviews. To obtain this level of support, you must teach managers the importance of reviews and work with them to integrate reviews within the planning process. Whether you can approach managers, and how to do so if that contact is permitted, depend strongly on the culture of your organization. But whatever the culture, getting management support requires two things: Examples of the kinds of significant errors that reviews have caught in the past, and the ability to explain this list to a manager who can encourage such reviews. Start documenting your review successes, and find a way to bring these successes to the right manager's attention.
In my writing, I emphasize the need to build good working relationships with our non-writer colleagues so often that people look glassy-eyed whenever I raise the topic again. But the point must be made repeatedly because Internet discussion lists for technical writers—such as TECHWR–L—make it clear that even those of us who understand this point often forget to apply our understanding to our jobs. If you can build mutually respectful working relationships or even friendships with reviewers, the task changes from a burden imposed by a stranger to help requested by a teammate or friend. Building these relationships involves interacting with reviewers on more than simply a business level: Eat lunch with them and find out about their families, team up with them against Management at the company golf tournament, help them write letters to their banker, and so on. Be honest, be helpful, be friendly—and be creative!—and you'll eventually break the ice. Someone who really wants to help you will do a much better job than someone who's only doing the work under protest.
Pick a time and review method that suit each reviewer's needs and preferences. Acknowledging that reviewers have their own job crises to deal with and showing your willingness to work around these crises gains you considerable sympathy. Find out each reviewer's own deadlines well before you ask them to review your documentation so you can schedule the review for when it won't conflict with those deadlines. It's harder to be unreasonable when someone goes out of their way to make an unpleasant or inconvenient task more pleasant and convenient.
If you've developed good working relationships with your reviewers, you've undoubtedly discovered that each has a different working style and different preferences for how they'd like to conduct reviews. Some reviewers can only review printouts of the documentation, others insist on working with word processor files, and some simply can't do a review unless it takes the form of a conversation or interview. (See, for instance, Conquering the Cubicle Syndrome.") Sending a printout to someone who works ineffectively on paper guarantees an ineffective review.
Edit documents scrupulously before submitting them for review. As Mark Twain once noted, few things are more human or more powerful than the desire to edit someone else's writing. That being the case, minimizing the number of trivial things (e.g., typos, incorrect formatting) that reviewers must correct forces them to concentrate on what remains: Technical matters that only they can review. Submitting poorly edited manuscripts to reviewers accustomed to having their own writing edited ruthlessly can also turn the review into "payback time" and encourage them to spend more time critiquing your writing than reviewing the facts they should be confirming.
Similarly, don't ask reviewers to fix problems you could have corrected with a little research, such as double-checking your writing against the product you're documenting. Careless errors such as using the wrong name for a menu or control device demonstrates contempt for their time; whether or not that's how you truly feel, such errors send the message that your time is so much more important than theirs that you can't be bothered checking details. That message undermines the cooperation you've aimed to achieve, and can undermine the entire review process in the long term. Asking reviewers to catch and fix obvious errors creates two additional problems: They can spend so much time focusing on these minutiae that they miss larger errors, and an abundance of little glitches can camouflage subtle but important errors. If you remove the small problems, reviewers can concentrate on the big ones, and the big ones have a harder time escaping their notice.
Few non-editors can maintain the concentration to effectively review 300-page manuals in one sitting, but just about anyone can review 30 ten-page chunks provided at appropriate intervals. Asking reviewers to check these smaller documents accommodates the non-editor's shorter attention span and lets them fit the reviews into small periods of free time. But don't ignore the consequences of breaking a single task into many smaller tasks; to some, reviewing a host of small manuscripts seems like the "death of a thousand cuts". These reviewers may prefer to simply sacrifice a full day of their own work and do the whole review in a single marathon session. The most appropriate document length varies among reviewers, and may change depending on the other projects they must complete. Ask your reviewers what they prefer before each review!
Never forget that a reviewer's ability to detect errors gradually decreases as they grow tired. That being the case, provide the most demanding or important information for review first, with reviews of simpler, less important information coming later in the review process. This obviously won't work when the product development schedule dictates your writing schedule, and works less well with strongly sequential documents such as tutorials, which may have to be reviewed in a specific order. But even in these cases, you can minimize the fatigue factor by requesting reviews early in the day, when the natural tendency is to delay starting other, more difficult tasks, or early in the development cycle, before repeated bouts of overtime wear down the reviewers.
Highlight your questions so they're as difficult as possible to miss and as easy as possible to relate to the text being reviewed. If you're working on printouts, use yellow Hi-Liter marker and numbers written in the margin that represent numbered questions provided on a separate printout. If you're working online, most word processors provide comparable features for on-screen reviews. In either case, use your knowledge of each reviewer's preferences and abilities to determine whether to ask questions by email, directly in the word processor file, or as part of an interview.
Never embed questions directly in the text, separated from the text by markers such as [square brackets] or ***asterisks***, or by formatting such as italics. Each such question is easy to miss, and many writers have been embarrassed to find these comments appearing in print or on a CD-ROM because the comments were neither addressed nor removed from the final files. Some writers have even embedded sarcastic comments or obviously incorrect phrases to test whether the reviewers were really paying attention; though this certainly proves whether the reviewers are paying attention, such comments also occasionally escape the final (always rushed) review and make their way into print, where they amuse or confound readers and serve as a lasting monument to your sense of humor.
Comments inserted directly in word processor files using their annotation features generally won't appear in the final printed copy, but reviewers can still miss them and leave important questions unanswered; for example, many authors adjust their screen display to conceal inserted comments or simply never learn to view the comments in the first place. Minimize this problem by adapting your approach to each reviewer and by rigorously confirming that they addressed all comments before you move documents to the next stage of production. Better still, work with them to ensure that they know how to view and respond to your comments.
Clearly explain to each reviewer what you expect from the review—in person, not just in writing. Reviewers can't easily ignore instructions they've discussed with you, particularly once you've confirmed that they understand your requirements and have negotiated how they can meet those requirements. It takes diplomacy to do this without seeming patronizing, but it's doable, particularly if you have a good working relationship with the reviewer. Explain your instructions in as much depth as the reviewers need rather than submerging them in detail; experienced reviewers may need nothing more than a reminder of the task (e.g., "I need a technical review, not a style review"), but others may actually need to work through a page or two of the document with you so they can understand the review process.
Even when you've successfully communicated your needs, provide written confirmation or a clear indication of where the instructions can be found; many writers place the instructions on the corporate computer network. People do forget conversations, and it's easier for some people to perform the wrong review than to risk the embarrassment of admitting they forgot what you discussed. Keep your instructions brief, since no reviewer will read a hundred-page style guide before beginning a review.
With all the deadlines that writers face, and the occasionally unpleasant people we work with, it's tempting to simply drop manuscripts in someone's in-basket and hope they'll review it properly. But that approach is rarely as effective as working directly with reviewers in a cooperative endeavor. Moreover, with some reviewers, discussing the document may be the only way to get good reviews. In my current work, I do all my editing directly in the word processor file; to complete the edit, I send the file to the author, then sometimes arrange a time for us to sit together in front of the computer and discuss my edits so we can reach consensus on the changes. As a writer, you can adapt this approach for working with developers, particularly when it lets you demonstrate usability problems that verbal descriptions don't handle adequately.
In typical offices, priorities can multiply to the point that reviewers forget your deadlines as they struggle to meet their own. In this environment, you should periodically remind them of review deadlines and—if necessary—renegotiate those deadlines or make alternative arrangements. The larger the document you've provided for review, the longer the review will take and the more likely that you'll need to check periodically on the reviewer's progress; it's human nature to procrastinate rather than jumping right into large, unpleasant tasks. Sending small sections of a much larger document to review makes the document appear less intimidating and doesn't trigger the procrastination reflex quite so strongly.
Reminders, just like requests for reviews and providing instructions for the reviews, should be conducted in person, over the phone, in print, or in email, depending on the reviewer's preference. You must also know your reviewers well enough to learn how frequently you can remind them before they grow irritated, and how frequently you must remind them to ensure that the job gets done on time.
Finally, consider some kind of reward system. Most of us never say "thanks" often enough, but even heartfelt thank-yous fail to motivate some reviewers. Tangible rewards often produce tangible results, so if your budget permits, try to provide such rewards. For example:
Your manager and the reviewer's manager can help you determine what kinds of rewards your employer considers appropriate. But avoid meaningless rewards such as laser-printed certificates crammed with cheesy clip-art; it's no coincidence that these have become the butt of jokes in popular comic strips such as Dilbert.
In the end, despite your best intentions and your best efforts to follow these suggestions, you're still going to encounter problem reviewers who simply don't want to do the work, or eager reviewers who simply aren't good at it. That's life. But if you can practice the approaches I've suggested until they become second nature, you'll greatly improve the success of your review process.
Hart, G.J. 1997. Accentuate the negative: obtaining effective reviews through focused questions. Technical Communication 44(1):52–57.
©2004–2024 Geoffrey Hart. All rights reserved.