Doc Reviews

This blog entry has been in draft form for, oh, a long time. Before I forget what I wanted to say, I thought I'd finish it this morning...

Document review meetings are a necessary evil of software development, no matter what you consider "a document" and no matter what your SDLC is.

Whether it's a quick PPT slide review, a white board session, or a formal design specification review, you have to get ideas out of one brain, on to some transfer media, and into another brain.

Given the difficulty of communication in general, and the compounding impact of distance and cultural/linguistic difference, it gets even tougher. So document reviews are important to get right.

I've done two approaches successfully:

1: Conceptual Walk-Through

In this approach, the author of the document isn't the one presenting it. Rather, the author finishes the document (to any level of detail, so this will work in light-process SDLCs too), publishes it somehow (steps away from the white board, sends a PPT out in e-mail, or checks a document in to source control), and gives the recipient or recipients a chance to read or review the document. Then, the recipient, or a nominated representative of the recipients, has the task of presenting the ideas in the document as a walk-through. In this model, rather than a line-by-line or section-by-section review, you're able to test that someone understood what was being presented. The author has to be the judge of the quality of the walk-through. If there are problems with the presentation, then you learned one of two things: Either the reader has poor reading comprehension skills, or the document is unclear about the key concepts or ideas it's trying to convey. Either way, you need to fix something. If the walk-through is clear and on target, then the document is OK, and you have communicated an idea or several ideas between the author and the readers.

2: Line-by-Line Review, with a twist

If you are still committed to line-by-line document reviews (and these only really work for big, long documents like design specifications, test strategy documents, schema definitions, etc.), then you will know that the biggest problem with a document review is that people seldom read the documents in advance. In every design review I've ever attended or run, there are several people clearly reading the document for the first time, IN the review meeting. This is a waste of everyone's time. So, to fix that, you can make a game of the pre-reading. Sprinkle the document with passages of Shakespeare, or your favorite public-domain author. Put in whole sentences, here and there. Count the number of instances of text you insert. (Oh, and save a pristine copy...) Distribute the document with the Shakespeare in it. When you call the Document Review meeting to order, ask people in advance to let you know how many instances of Shakespearean prose they found in document. Do the section by section review, then at the end reveal the number of instances of Shakespeare, and give a prize to the person or people who got it right. There are arguments to be made that this will get people to skim the document looking for "Now is the winter of our discontent," but in practice, I've found that this methodology does get people to read and review the document in advance, and makes for a more productive and interesting document review meeting.

Your mileage may vary, as always.

No comments: