Distribution and review strategy?

[Geoff Hart]

Peggy Lucero wonders: <<It is now time to solicit [reviews] from a team 
of about 10 developers on a 1100 total page System Design Document that 
has been broken down into 7 parts (each a separate WORD document).  
Document is stored on SharePoint and all team members have access to 
it... I'm struggling a bit with determining the best method to obtain 
the developers cooperation in the review process as I don't have a lot 
of experience with this.>>

First and foremost, a job that large simply isn't going to get done 
well, if at all, without some serious buy-in from the developers. You 
mention that they "appear have a near zero interest in the 
documentation", suggesting that you're not going to get that buy-in 
easily. Most times, you need a carrot and stick approach: you want to 
encourage them to do it by a judicious balance of rewards (preferably) 
and threats of corporal punishment if they don't cooperate (as a last 
resort).

This means you need to obtain support from their managers or the 
managers who will suffer most if the review isn't done. If the managers 
won't back you in this, you're going to have a tough time: you can't 
force the developers to cooperate, and unless they particularly like 
you or owe you favors, you probably can't get them to do this much work 
unless someone empowers you to provide incentives.

If you can get some kind of buy-in, through fair means or foul, the 
trick is to make it as easy as possible on the reviewers. The more you 
are seen to be considerate of their needs, the more likely they are to 
cooperate and to do a good job. Start by talking to each one to find 
out how they'd prefer to do the reviews. For example, if a key reviewer 
hates to do online reviews, but your policy insists on such reviews, 
offer a compromise: let them do the review on paper, and you can 
transfer the comments into the files for them.

Second, find out which ones are most qualified to review each document 
or each section of a document, and focus your efforts accordingly. 
Don't ask everyone to review all 1100 pages if they're only competent 
to review 110 pages each; on the other hand, if they're all equally 
competent to review all the text, divide up the workload. Ten reviews 
for each document is almost certainly overkill, and three reviews is 
probably effective. They'll love you for finding them a way to review 
(for example) only three of the 10 documents.

If any one document is particularly critical (e.g., it could cause 
expensive losses or injury to readers if errors slip through), put the 
most expert reviewers or the greatest number of reviewrs on that job, 
and get it done first. That way, if review fatique sets in, you know 
that the most important stuff was checked thoroughly. The rest of the 
stuff can wait because errors won't kill anyone. (Think "triage"!) For 
stuff that is particularly crucial, put more developers to work on it; 
you may want all 10 reviewers to look at one paragraph in a given 
document, 5 reviewers to look at one section of that document, and 3 
reviewers to review the whole document.

A few resources (because it's Friday, not all entirely serious*) that 
should inspire you:
http://www.geoff-hart.com/resources/1995-1998/negative.htm
http://www.geoff-hart.com/resources/2000/persuading.htm
http://www.geoff-hart.com/resources/2001/physics.htm
http://www.geoff-hart.com/resources/2001/inspiring.htm
http://www.geoff-hart.com/resources/2002/wildreviewer.htm
http://www.geoff-hart.com/resources/2005/reviews.htm

* The less serious ones do have some insights; if not, they at least 
have the virtue of being brief.

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