Documentation review?

Subject: Documentation review?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, Peggy Lucero <plucero -at- atsva -dot- com>
Date: Wed, 28 Dec 2005 09:51:24 -0500

Peggy Lucero wondered: <<I have 10 technical documents, varying in length from 60 to 600 pages. They need to be reviewed, starting 2/1/06 and ending in mid April.>>

No miracles required. Worst-case scenario (6000 pages in total, 20 days per month), that's less than 100 pages per day, and if most of the books are smaller than 600 pages, the task becomes feasible. Provided the material was carefully prepared and is well edited before it goes for review, this is an achievable target.

<<They need to go to: 1. Peer review 2. Client review>>

The first question to ask is how many reviewers there will be; more means less chance of reviewer burnout than if each reviewer must review each document. Consider giving your reviewers a break by assigning reviews to the person most qualified to do them instead of forcing one person to review everything. The second question is about whether the peer and client review can be conducted in parallel. If they can, the problem becomes easier. If not (often the case), you cut your time for each phase to only about 1.5 months, and that makes the pages per day climb into the potentially unachievable range if each reviewer must review each document.

<It seems a consensus that 5 days are ok to allow as the time period for each document to be reviewed in, though for the one really long one (almost 600 pages), I've recommended a group review meeting, that I'm suggesting will take 4-5 hrs, but, I actually have no idea how long it is likely to take.>>

Setting a single review period for documents of different lengths is at best unkind to reviewers who get shackled with the longer documents, and at worst, a lousy way to estimate review times and schedule the reviews. All else being equal, review time is directly proportional to the length of the document--that is, longer documents require more time. So always set review durations based on days per page.

Here's one data point. I edit very quickly compared to most--ca. 1100 words per hour for two passes with heavy substantive editing. Double that because your reviewers will typically make only one pass (2200 words per hour) and because they won't be doing heavy editing. This means (conservatively) about 4 single-spaced pages and 9 double-spaced pages per hour. Call it 5 and 10, respectively, to make the calculation easy. Now let's assume 5 hours per day of review time (probably a bit high if reviewers actually have their own work to do, but the calculations remain easy). That means 25 and 50 pages per day, respectively. Now you can estimate a "fair" review time for each document based on these rates. Real reviews should go faster.

Second, time requirements depend heavily on reviewer availability. Find out when each of the reviewers is most likely to have time available for the review, get their commitment (ideally "in person" or over the phone) to do the review at that time, and send them the review at that time--not earlier, unless they're willing to renegotiate the deadline, and definitely not later. Find out their preferred review format (Word file, PDF, printout) and send them that. Confirm their availability a week or so in advance of the scheduled review, and have a contingency plan in case they have to bail at the last minute because of some life crisis.

Third, review meetings are generally the least effective way to review a whole document. If you must use a meeting, make it efficient: review all the edits and comments before the meeting, and at the meeting, discuss ***only*** the areas where reviewers disagree. Send everyone a copy of the disagreements several days before the meeting so they can think them over, discuss them with the other reviewers, and come to some consensus (so you can record their agreement and remove it from the agenda) or agree to disagree (so you need an in-person meeting with you arbitrating to broker a compromise).

<<... no two documents overlap. In other words, I'm only to give documents one at a time to a reviewer because if they get more than one at a time it is believed they'll get 'overloaded' and never get anything reviewed and returned to me.>>

This is a real risk. Plus, large documents can create a massive psychological impediment to getting started, plus a desperate need to burn through the review rather than taking the necessary time. Consider sending reviewers small chunks (e.g., chapters or sections) rather than the whole manuscript. This makes it easier to fit the reviews into a busy day (you can edit a chapter over lunch, but knowing that you can't do that with 600 pages may lead you to spend lunch playing Tetris instead) and gets the job done sooner. Of course, ask their preference: some people (editors like me, for instance) really do prefer to get the whole manuscript at once and slog through it.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
www.geoff-hart.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l

Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author content and configure Help in MS Word or any HTML editor. No proprietary editor! *August release. http://www.componentone.com/TECHWRL/DocToHelp2005

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


Follow-Ups:

References:
Documentation review: From: Lucero, Peggy

Previous by Author: Don Norman on Manual Writing?
Next by Author: Do Document Reviews Provide Signifcant Feedback?
Previous by Thread: Re: Documentation review
Next by Thread: RE: Documentation review?


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads