Software Design Reviews – what are you reviewing?

Software design review time. The selected reviewers have been handed a document that they have diligently read. They then meet to go over any comments  … but what are they actually reviewing? Are they reviewing the design described in the document or are they reviewing the document itself?

With the availability of excellent source code formatting utilities in most development environments, code inspections no longer need to nitpick about the layout of the source code. However, when it comes to design reviews, most are still described in hand-written documents. The authors of these documents are frequently expected to comply with some design specification document standard or template.

There is nothing intrinsically wrong with having a standard or template. The problem comes when a team of reviewers spend more time pointing out non-compliance in things like the fonts, paragraph and heading styles used, trivial grammatical correctness, and the lack of introductory content than in the design being described.

Yes, a design document needs to communicate design adequately, but it is far more important to get the design right. Correctly formatting a design document to effectively communicate a poor or broken design is a waste of time.

There are times when reviewing the document is required; when the document standards or template are set by regulators or by a formal contract. However, that is a document review not a design review. Beware confusing the two. A design review is far more important than a document review, even when the document review is truly needed.

Of course, a tool that generates a document from artifacts produced during the design process (whether that process be upfront, purely iterative or somewhere in between) alleviates much of the document formatting issues, in the same way as code formatters do for code inspections.