Reviewing Requirements Documents

You may have heard the expression “shift left testing,” where testers get involved earlier in the software development process than they had previously. (This is expanding testing to the left, if you drew out the steps in the process from left to right.) 

One way to shift left is to review requirements documents. A requirements document could be lengthy, with lots of words and diagrams, or it could be very brief like a user story, or something in between. The important thing is that it sets the direction for a discrete piece of work. A mistake made in a requirements document is likely to be expensive to fix. Review is a good way of trying to spot these mistakes while they’re still cheap and quick to fix. 

The Purposes Of A Document Review

The main purpose of reviewing artefacts like a requirements document, code, or tests is to increase the chance that the artefact is fit for the intended purpose, which is what this article will concentrate on.

However, it’s important to not ignore the secondary purposes of review, which relate to people. These will be covered briefly in The Human Dimension below. 

The Human Dimension 

A review is a way for people to learn.  They can learn about the document itself, but also about the way the author came up with the document. What did the author consider (and what did they not)? How did they reconcile competing demands? How do they propose to solve problems? How do they express themselves?

A review is also a venue where the culture of an organisation such as a development team can be seen in action. What is important to the team and what’s less important? What’s allowed and what’s not? Whose voices and opinions are heard? How comfortable does a junior team member feel when pointing out a fault in something produced by a senior colleague? Are they even able to do this?  How much risk is there to the process and outcome because some people’s contributions are being ignored?

Reviews should not be where people show how clever or senior they are. They should not be about point scoring. They should be thorough but also respectful.  The authoring and review process can be a challenging balancing act — an author should care about their work so that they do a good job, while at the same time they should not be so bound up in it that they reject criticism of it or get upset by it.

It’s important to keep separate the document and the author. Reviewers are supposed to find problems with the document, not with the author.  Language can help with this. If you say “the document” rather than “your document” it can make it clearer what’s being scrutinised. 

It’s for the team to work out what level of detail is appropriate. Is pointing out a typo low-value nit-picking or is it spotting a crucial detail? 

Three Approaches For Review 

There are three approaches when a requirements document is reviewed. They are all valid, and can find different kinds of problems with the document. The approaches are: 

1. Reviewing the document in isolation, that is to say, reviewing only what’s there  
2. Reviewing the document against a set of related documents, or in other words, reviewing against the support structure 
3. Reviewing the document against everything else, including the existing system 

These will be described below.

Reviewing The Requirements Document In Isolation 

This involves reviewing the requirements document by itself as a piece of technical writing. Is it clear, concise, complete, unambiguous and free from contradictions? Put another way, it’s answering questions like:

• Does this make sense? Would it make more sense if there were, for example, a diagram? 
• Is there anything obviously missing? 
• Is there anything that can be cut or shortened? 
• Can this be easily misinterpreted? 
• Do the parts of the document agree with each other? 
• Is it easy to navigate the document — to know where you are, what the purpose of the current section is, and where to go to find other bits of information? 

Reviewing Against A Set Of Related Documents 

It might seem that a requirements document is the top of the tree of related documents, but this often isn’t true. The document might specify only part of a larger whole; for example, one user story within an epic. In this case there is a parent document of some kind as well as sibling documents to cover the other parts of the larger whole.

The requirements document can be reviewed against the parent document, to make sure that it covers all the tasks delegated to it by the parent. Also, it’s worth reviewing against sibling documents, to make sure that the parent task is correctly covered, that is to say, there are no gaps or overlaps.

Even if there is no direct parent document, there are often documents against which the requirements document can be reviewed. These are often policy and strategy documents that exist in the background behind all individual bits of work. The documents could cover things like security, user experience, response times, resilience, and so on.

Policy and strategy documents often have a bad name, which they sometimes deserve, because they are little more than officially-blessed electronic paperweights. Ideally, they should help people to make decisions or take action.  For instance, when reviewing a requirements document, a reviewer should be helped to decide whether the requirements document is likely to produce security problems.

If the policy and strategy documents don’t help with decisions and actions, it is worth investing time and effort into improving them.  A way to review requirements documents well is first to have good strategy and policy documents.

It is important to consider combinations of requirements. This is especially true when the component requirements come from different documents, which will make it hard to think of them as a whole.  Requirements that seem to make sense on their own can cause problems in combination if they pull in opposite directions. For instance, one requirement might pull the system in the direction of complexity, while another requirement asks for a system that is quick and easy to learn.

Reviewing Against Everything Else 

This form of review is often the hardest of the three mentioned above, because it’s hard to gather together the things that the document will be reviewed against. It is probably too hard to think of every detail of the existing system when reviewing a requirements document.  There are three lenses that can be useful for focusing attention on different areas of the system to give useful context for the review:

• The main bits of data that the system uses 
• Interfaces with third party code 
• Uses of the system by different groups of users

All of these should be used at a high level of abstraction and granularity, rather than worrying about; for example, exactly how many characters are allowed in a particular text string.

When thinking about data, consider the most important bits of data that the system uses.  Think about the full lifecycle of the data — how it is created (or, at least, enters the system), how it is used by the system, and how it is finally deleted.

Interfaces could be in the form of code or data. The interaction across the interface could be started by our system or by a third party. They could contain a lot of data, or very little, as in the case of notifications that something has happened.

Systems often can be used by more than one group of users, where the average or common use cases for each group are different from those of other groups.  Some of these users might be internal, your colleagues, for example, while others might be external.

The idea of the lenses is to help you to remember the important parts of the system, so that you can see how the requirements fit with the system as it already is. 

Conclusion

Reviewing requirements documents is a valuable activity, and one where testers can contribute a unique perspective. It’s a potentially big and ill-defined task, so it could help to break it down into: reviewing the document within itself; reviewing it against a context of related documents; and reviewing it against the existing system.

As well as concentrating on the document being reviewed, it’s important to remember the people involved. Done well, a requirements document review can allow people to learn and to feel valuable.

For Further Information

• Ministry of Testing Panel Event — Shifting Testing: Left Or Right?
• The Hidden Treasure of Static Analysis: Finding Risks in Forgotten Places, Hilary Weaver-Robb