The Case for Reviewing Requirements and Design Documents

  März 20, 2019

If a document is going to be produced, it should be reviewed. In this article, we examine why development teams should do document review on technical documents like requirements, user stories and design documents.

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.

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 on 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 writing 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.

Stay Up to Date on Peer Review Trends
View our interactive report on peer review trends and insights

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.

Supercharge Communication Throughout The Development Process

With most development teams being distributed globally, your development process requires an efficient feedback mechanism within a tool to ensure you aren’t losing any velocity or time while collaborating across time zones. A developer collaboration tool, like Collaborator, makes it easy to review user stories, requirements, and code, communicate across the team, and deliver quality software all from one interface.

Additional Resources

Start Your Free Trial
Start a peer code review program with Collaborator