Should You Review Requirements and Design Documents?

Editorial Note: I originally wrote this post for the SmartBear blog.  You can check out the original here, at their site.  While you’re there, have a look around at posts and knowledge from other authors.

I remember working in a shop that dealt with medical devices some years back.  I can’t recall whether it was the surrounding regulatory requirements or something about the culture at this place, but there was a rule in place that required peer review of everything.

Naturally, this meant that all code was reviewed, but it went beyond that and extended to any sort of artifact produced by the IT organization.  And, since this was a waterfall shop, that meant review (and audit-trails of approval) of the output of the requirements phase and the design phase, which meant requirements and design documents, respectively.  I can thus recall protracted meetings where we sat and soberly reviewed dusty documents that made proclamations about what “the system” shall and shan’t do.  We also reviewed elaborate sequence, flow, hierarchy, and state design artifacts that were probably obsolete before we even reviewed them.

If I make this activity sound underwhelming in its value, that’s because I routinely felt underwhelmed by its value.  It was a classic case of process over common sense, of ceremony over pragmatism.  Everyone’s attention wandered, knowing that all bets would be off once the development started.  Sign-offs were a formality — half-hearted and cursory.

But is it worth throwing the baby out with the bathwater?  Should the fact that waterfall shops waste time on and around these documents stop you from producing them and subsequently reviewing them?  Is it worth reviewing requirements and design documents?

The Case for Requirements Documents

I’ll start off by laying my cards on the table.  I’ve spent the last 4 years or so working only on agile projects, making my version of requirements the “user story” (or, depending on the situation, a “use case”).  That has worked quite well for me; I’ve left the formal requirements document in the rearview mirror and never once missed it.

But for me to say that my not missing it means that it adds no value for anyone is short-sighted.  There are plenty of stakeholders and people in need of software that just seemed to be wired for this sort of thing, and agile-minded software developers can’t simply turn every project into a detailed lesson no how to be agile.  Not to mention that the needs of the project need to be expressed somehow, and a requirements document is better than nothing.

The Case for Requirements Document Review

If this document is going to be produced, then it should clearly be reviewed as well.  In shops (waterfall or otherwise) that start with a document or document(s) detailing software requirements, software developers are likely to be minimally involved in the initial conception.  So, at a bare minimum, the existence of such a document should make the need for its review completely obvious.  It’s the technical staff’s chance to attain clarity and provide feasibility pushback.

But there’s another, more subtle mission that I’d propose for the review, given my own proclivities.  Not only can you use the time to make sure that people understand and vet the proposed requirements, but you can make the creation of user stories a part of this meeting.  This proves invaluable in confirming understanding, since you’re actively restating the requirement in a value-oriented format.  Doing this will keep everyone engaged and involved and result in output that tends to be easier to reason about and move through for developers.  ‘Sign off’ then comes when the original document has been transformed into user stories.

The Case against Design Documents

Remember how I said that we shouldn’t force requirements-document-happy stakeholders into abandoning the document because agile?  I bet you were thinking that I’d have to make the same case for design documents as well, but I won’t.

Being willing to live (temporarily) with imperfect requirements documents makes sense because it allows for progress even when people requesting software don’t know how best to express the request.  But design documents are purely an internal affair.  In waterfall shops and shops that “sign off” on designs prior to development getting started, you’re not talking about clarification of what needs to be built, but of how it should be built.

In other words, design documents are a communication from architects and managers that says, “I don’t trust you, newbie, so lay out in lots of detail how you plan to tackle this before you go running off unsupervised to do it.”  And this is an organizational anti-pattern.  If you don’t trust the newbie, pair with him or provide frequent code reviews.  Don’t engage in some kind of excruciating exercise in Word documents  and charts that have to be pre-approved.

The Case for Design Review

Am I then saying that design documents have no place?  It might sound that way, but I am most certainly not suggesting that you forgo design, or even design documents.  Rather, I’m suggesting that you forgo “sign-off” and storage of these documents, to be updated later with a change request when reality (inevitably) causes them to change.  As I mentioned in the second paragraph, design documents are invariably obsolete as soon as people start writing code — so why bother with pre-approval and with constantly updating the things as you go?

Forget the formalism.  Have design sessions, but do it on whiteboards or tablets.  Writeup documents, diagrams and flow charts if they help you, but use them to communicate and get started.  Call design review meetings, by all means, but have these be about enablement and not approval.

General Wisdom

It’s worth bearing in mind that the purpose of review in general should be to improve work product, to spread knowledge, and to collaborate.  In a world dominated by formalism, which can often happen at heavily regulated companies, it’s easy to lose site of this goal in favor of box checking.  But if you want to be at your best, it’s important not to let this happen.

If you’re going to participate in activities, particularly ones with output, it’s worth having peer review around them.  But it’s just as important to make sure you’re only participating in activities that add value.