Reviewing Documents

Considering how much work goes into reviewing documents, designs, books, code, etc., I find it surprising how little guidance there is on the topic.

Quick Google searches pull up mostly information technical features of programs, like Word or Acrobat, to compare documents. Digging further brings up some scant information on holding reviews, mostly focusing on planning aspects, and sometimes giving useful advice for authors, like “listen to make your ideas better, not learn to defend your ideas.” What is totally lacking, however, is any advice on how to participate in a review effectively as a reviewer.

This is interesting because the way reviewers participate can have significant positive OR negative impact on a review. The worst reviews gather a large group of people, none of which have read the documents, and spend inordinate amounts of time focusing on nit picking little details. Good reviews use many communication channels, separate reading and discussion times, and only use discussion time for topics that:

1. Require group input or consensus.
   
2. Are intended to convey meaning to the group.
   

To a degree, I believe the reason why advice on reviewing documents is neglected, is people assume it is the author/facilitator’s responsibility to insure quality reviews. In part, this is true, but there are limits to the influence of authors/facilitators.

So how can you do better as a reviewer? The number one task is to read the document. Sure, it sounds obvious, but it is so commonly not done, that it is worth the reminder. If you do not have time to get it done before the review meeting, consider selecting a few sections and focusing on those. It might be best to try to choose something other than the first sections, since others may start and end here.

We all know time is limited so I doubt everyone will comply 100% with this suggestion. When I have failed to read a document prior to the review, sometimes I have been left wondering if I would have been more effective to skip the meeting and spend that time at my desk reviewing the document. This is especially true if no one else had read the document, and thus no topics of real importance were discussed.

My second tip is to choose the right channel to communicate. The worst thing you can do as a reviewer is monopolize discussion time to convey grammatical issues, style issues, and other one-sided issues or nit-picking issues. Depending upon the type of document, and its purpose, this kind of information can be extremely valuable, but it does not warrant discussion.

The best thing to do with such issues is to send them to the author before the review. Usually authors, when they get this kind of feedback, will simply say “doh!”, and fix the problem. If you and the author agree, there is likely no need for discussion. If you disagree, let the author ask the question. On highly opinionated, but relatively unimportant concerns like style, it is usually best to throw your 2 cents in and drop it there. If the author likes the suggestion he will say “Why didn’t think of that?” If not nine times out of ten, you will not get your way, and even if you do, there may be little benefit.

In some cases, like code reviews, it may make sense to have the author communicate which suggestions he accepted, rejected or feels require further discussion. More traditional prose documents, for issues like grammar and style, fit a fire-and-forget style of suggestion better. If you make the process to heavy for you or the author, either you will avoid making suggestions that could be valuable, they will unduly burden the author, or both.

The way I do this, is I take a copy of the document, and revise it the same way I would a draft of a document of my own (It’s important to remember to use a copy, or you’ll receive great, and justifiable, ire from the author ;p). You should use a tool that has revision tracking, and if possible, make sure that the only revisions that show in your copy are your own. Also, find another way of indicating the big issues, like as a separate email, or only use comments for big issues.

One of two problems I have with this strategy is that I can end up too focused upon the minor myself, and not see the bigger issues. On the other hand, that first read turns out to be fairly thorough, and if I go back and skim through again, I have a much better understanding.

Spotting the big issues is the most important part however, especially in early drafts. Quite often, you’ll just produce more questions. You might have additional content that needs to be covered. Whatever it is, big questions will usually require a second go around or more. These are the types of issues that might warrant discussion.

As important as it is to use the correct channel for small issues, it is equally important to insure that authors are given forewarning of big issues. It is impossible to do this if you did not read the document ahead of time, so this is one more reason to make sure you read early, preferably the day/night you get the draft. One reason why this is so important is so authors can be properly prepared for a discussion, and will not be forced to respond with a “I’ll look into that…”. Another reason is to help the author maintain his cool, and not get defensive. It is, at least in my opinion, a lot easier to take objectively criticism if it is not piled on in large doses in a 1-hour discussion. It is also far easier to take if when you are not put on the spot and (figuratively) asked, “Hey you, did you screw up?” If the author can respond, “Yes, I made a mistake, but I know how to fix it”, not only will more get accomplished, but he will feel better about the experience.

The second problem I have with my strategy, is that it is important to insure you are changes are properly received. “Rewriting” a document can be interpreted as presuming too much. In truth, it is the most effective way to communicate suggestions, but it is quite easy to see how the receiver might interpret it as assuming your way is right. However, as long as the author knows that he can either use or ignore the suggestions, you should be okay. I think it is better to offer an alternative, than to simply plug in a generic “confusing, try rewording?” comment.

Of course, all this comes from the perspective of a programmer\architect. I wonder if what works is fairly universal, or if it’s a lot different for things like books, movies scripts, marketing plans. What do you think?