Five practices for better requirements

Writing requirements is not an easy task. It requires discipline and preparation, especially if you define requirements in a natural language. Many professionals dislike this activity and perceive it as dull and tedious. Ivy Hooks discussed this phenomenon and listed improvements that an organization can pursue to change this situation. As a consultant, I often have clients who struggle with their requirements development activities. To help them, I advise using several specific practices that benefit anyone who has to write requirements. Over the years, these practices helped many, and today, I will share them with you. These practices are:

1. Identify stakeholders and other sources of requirements.
2. Prepare your elicitation efforts.
3. Define the solution boundary (explicitly).
4. Phrase requirements with the structured language.
5. Organize requirements for readability.

Let me explain each practice separately in more detail.

1. Identify stakeholders and other sources of requirements.

Requirements always have a source: a stakeholder, a previous product, a standard. Knowing where your requirements come from helps you achieve the completeness of your requirements set — missing an important stakeholder or a critical regulation results in missing requirements. If we discover this issue later in the development, the cost of incorporating the missing requirements into the solution may be costly and result in delivery delays. Therefore it is recommended to spend some time upfront to identify stakeholders. Then we can analyze how they contribute to the requirements activities. Next to stakeholders, the requirements may be derived from other sources like regulation, standards, contracts. Identifying these documents is a critical activity that contributes to better, more complete requirements in the long term.

Improvement idea: Create and maintain two overviews:
• A record of stakeholders critical to your initiative. Additionally, keep a short characteristic of each of them, so the stakeholder’s role in the requirements activities is evident.
• A list of standards, regulations, and other formal documents from which you derive requirements.

2. Prepare your elicitation efforts.

It is easy to get distracted during elicitation. Therefore knowing who your stakeholders are and their role in the requirements elicitation helps you define the best way to approach them. You have to decide what elicitation strategy is the most appropriate. Here a word of warning.
The research shows that the elicitation techniques are not selected based on their suitability to the business situation. Instead, Business Analysts chooses a method based on how proficient he is with it. Doing so is like trying to use a screw and a hammer. They do not fit together, but you will use the hammer in this situation just because you know how to use it. Consequently, the result of the elicitation may not be satisfactory. Therefore, when preparing the requirements elicitation, you need to consider:
• the nature of your project,
• the characteristics of the business situation, and then
• select the most appropriate techniques based on the advantages and disadvantages of elicitation techniques.

Improvement idea: Know your tools, create an overview of elicitation techniques you know, and use. List their advantages and disadvantages. Then extend your list with techniques you are less familiar with and try them if they are suitable for your elicitation work.

3. Define the solution boundary.

In the real world, boundaries are agreements between sides. This agreement defines what is within the boundary and what is outside of it. The same process holds for requirements. Before we start writing them down, we must be clear about the solution’s boundary. And because it is an agreement, it has to be appropriately documented—many requirements’ conflicts origin from a misinterpretation of this boundary. A simple practice that helps to define a boundary is to use a context diagram.

A context diagram depicts the solution in its environment. The oval in the middle defines the solution under development, and the rectangles around it represent external entities that interact with the solution. External entities may be a human actor, another system, or a function, as presented in the figure below. The lines linking external entities with the solution indicate an interaction between them.

How does the context diagram help in requirements writing?

Firstly, it helps identify external interfaces that the solution shall support. Every set of connections between an external entity and the solution implies there is an interface needed. Each identified interface needs a set of requirements defining it (in the requirements specification). Secondly, it helps write requirements on the right abstraction level. If you follow the context diagram, you will document them from a solution point of view. These requirements will define what the solution will do, with what qualities, and under what constraints. Every time you want to write a requirement about a part of the solution (one f the gray circles inside the solution), you know these requirements are on the wrong decomposition level and belong to other requirements documents. Thirdly, if you expect something from the external environment (one of the external entities), you can define your expectations clearly as assumptions.
A context diagram, however simple, can offer a lot of guidance to requirements writing.

4. Phrase requirements with the structured language using templates.

Requirement templates are structures that you can use to write a requirement statement in a standardized way. There are many benefits of working with templates:
• Standardized formulation: The requirement template forces requirements to be written down in a certain way, helping similar requirements look alike.
• Prevent ambiguity: The rigidness of the requirement template prevents vague language and encourages specifying the exact meaning.
• Prevent inconsistencies: A more precise language and specification of purpose help developers and other stakeholders see dependencies between requirements, thus preventing inconsistencies.
• Uniformity of language/consistency
• Easy to use: Requirement templates are written in what is called a semi-formal language.

There are many ready to use templates available on the market as a start. You also can use these templates to define specific ones for your organization if they do not suffice. Requirement templates are an agreed syntax for the requirement statements. However small thing it might be, many professionals are truly helped with them, so give it a try.
I take an example from the IEEE standard 29148 Systems and software engineering – life cycle processes – requirements engineering that defines a possible requirement sentence structure as:

[Condition]+[Subject]+[Action]+[Object]+[Object’s Details].

When the battery power level drops below 10%, the laptop shall adjust the screen’s brightness level to 45 [unit].

If you are interested in the requirement templates, don’t hesitate to contact me by sending me an email at info@bacoach.nl.

5. Organize requirements for readability.

Creating a readable requirements document is a challenge on its own. Many professionals use the company’s templates because a requirements document template reflects the lessons learned from previous projects. Although useful, these templates also contain chapters that professionals see as a pain in the neck, e.g., the intended audience section or an overall solution description. Yak! Why not start with requirements immediately? However, it might be seen as bureaucratic; these chapters help us write readable documents.
The ISO standard 29148:2011 (and its predecessor ISO 830-1998) recommend a structure in which a document contains three distinct parts.
1. Introduction – in this part, you indicate who are the recipients of your requirements. It is essential to know who will use your document to tailor your information, level of detail, and language to the audience. This part often contains a glossary section to explain all terms that might be misunderstood or need definition.
2. Overall description of the solution – in this part, you document the solution boundary, interacting systems/actors with additional characteristics, constraints, and assumptions (on the context in which the solution has to operate). This chapter introduces readers to the requirements that will follow.
3. Requirements – in this part, you write down the requirements. You can organize requirements in many different ways: by a function, by a feature, by a data element, by an external interface, or by a process. The division depends on many aspects, and you need to sit down and decide what the best structure is. You should include some of the recipients, too; this document is for them in the end.
An additional aspect that contributes to increased readability is the inclusion of models and pictures to your document. Most of the readers are visual; mixing text and graphic elements (diagrams, pictures, tables) increases engagement and contributes to forming a shared understanding.

Conclusions

Well-defined requirements benefit every project. It is not an easy task to define them. The five tips I share with you in this article have proven to work for many. These are not very difficult things to do, but they do require some discipline in your activities. Try them, and you will see the difference.