Writing requirements is not a trivial task. Despite of many books, courses and publications on this topic, the practice shows that those who write requirements have to practice a lot to produce good quality requirements. Last couple of weeks I was asked to review some requirements documents. These reviews inspired me to write this article to remind us about where the problems with requirement are coming from. I also share with you a couple of practical writing tips which application can help you to come up with better quality, unambiguous requirements.
One of the important functions of a requirements document, and thus requirements, is to allow and to facilitate communication between a project team and its stakeholders about what this project shall deliver. This communication happens mostly in a natural language, which is ambiguous, vague and imprecise by nature.
To understand the communication problems we can consider the Osgood- Schramm communication model with a sender (person A) and a receiver (person B), see figure 1. Communication begins with a person A, who encodes his thoughts into a message. This message is sent to a person B by a certain channel – it can be a.o. paper or air (in case of requirements documents we often use paper as means for written communication). The message arrives at person B who has to decode it. In order to decode the message the person B has to know the rules how to do it. Lastly, the person B interprets the message (using the rules) giving its meaning.
Figure 1: Communication model
Looking at this simple example we can see how complicated this process is. There is no guarantee the decoding and interpretation steps of the message on the side of person B will be the same as the encoding and interpretation steps of person A. This makes the communication vulnerable to mistakes. Let’s imagine two people talk about a small dog, person A has a French bulldog in mind. When not communicated properly the person B can decode this message and interpret it that a pincher is a subject of a discussion. Don’t you experience this mismatch yourself when discussing requirements with your stakeholders? Don’t they resemble the famous requirements swing cartoon we all know? (Figure 2)
Figure 2 Requirements swing cartoon
There may be many reasons for miscommunications like language differences, cultural differences, personal differences. Where with verbal communication we still have a possibility to spot the communication mismatch by e.g. analyzing the body language of receiver, with written communication such a validation is more difficult if not impossible. Knowing that a requirements document is a form of written communication and understanding how the communication works and where problems can occur, how can we minimize miscommunication when writing requirements? Here are some simple and practical guidelines which you should have in mind when writing requirements:
- Keep sentences and paragraphs short,
- Write requirements in the active voice,
- Prevent negative (or inverse) requirements,
- Write complete sentences with proper grammar, spelling and punctuation,
- Use terms consistently – define them in a glossary or data dictionary,
- Use a limited vocabulary – a simple subset of English, avoiding terms that may confuse non-technical or foreign readers,
- Avoid conjunctions (and, or) that make multiple requirements,
- Avoid let-out clauses or words that imply options or exceptions (unless, except, if necessary, but),
- Focus on stating what result the requirement will provide for a stakeholder,
- Use templates for requirement sentences e.g. The shall provide to achieve . or As a <role> I want <something> so that <benefit>.
Many of us experience problems with requirements, either as an author stressing out to formulate them properly, or as recipients who have to approve or to implement them. Because requirements are written down in natural language, which is imprecise and vague, there is no simple way to make them “bullet proof”. Using ten tips can help you in improving your requirements and making them less ambiguous. These tips seem simple, and they certainly are nothing new. However they require a lot of discipline to apply. If you want to apply them, choose a couple of them to start with and extend gradually the set of rules you apply as your “requirements writing” muscle gets stronger. Remember that practice makes better, striving for perfection, in this case, is not an option.