Requirements Engineering: Documentation of Requirements

Requirements Engineering (RE) is an expansive term within the framework of a project meaning to gather everything you need in advance in order to make the project successful. As we have already dealt with the identification of goals and the initial requirements for a project as well as the pros and cons of the whole process in general, it’s now time to move on to the next step - how to document identified requirements. To make documentation understandable afterwards, there are certain criteria how good requirements can be recognized.

Criteria for good requirements

These requirements or criteria are sometimes quite simple and self-evident – but occasionally a bit more difficult to understand. A good requirement should meet the following criteria:

• Coordinated (correct for all stakeholders)
• Clear (unequivocal)
• Necessary (must be valid)
• Consistent (without contradictions)
• Verifiable (a test enables verification)
• Feasible (organizationally, legally, technically, financially)
• Traceable (why do we want to do this?)
• Complete (no gaps in interpretation)
• Comprehensible (for all stakeholders)

This does not necessarily imply that a requirement which fails to satisfy all these criteria is irrelevant. It just means that it can sometimes be more challenging to work with afterwards. The aspect of “traceability” is a little hidden, but nevertheless very important. As shown above, its purpose is to determine why this requirement makes sense or where it comes from. This is crucial as the reason for a requirement is sometimes forgotten over the course of a project. When this happens, it could be argued that the requirement itself is irrelevant, but that is often a fallacy. For example, if new members join the project team, they may need to familiarize themselves with the requirements.

Where to get your requirements from?

We already came up with some initial requirements in the AND-OR tree of our model project, even if they do not yet meet all of the criteria. Our stakeholders were the main source of these requirements. Other sources include a variety of standards and laws as well as competing, previous and legacy systems. In our model project, they would sometimes be incentive events organized by other teams or previous events within the same team.

The simplest cases involve interviewing the stakeholders and reviewing documents to determine the requirements and their priorities. Besides that, there are various other techniques that will not be addressed in more detail in this series, such as observation or creative techniques.

Notation of requirements

I have had good experience with the use of sentence templates to note requirements. The structure is always the same and the content is (completely) detached from technical implementation. The sentence template I use – like many other people probably do as well – looks like this:

Once again, there are a few challenges that need to be considered when using the sentence template. Anyone looking to investigate this issue in more detail can enter the following keywords in their preferred search engine: ambiguity, transformation effects, nominalization, nouns without reference index, universal quantifiers etc. Apart from that, English grammar must be taken into account as well, and the noun should always be at the start of the sentence if there is no condition.

Requirements for our model project can be defined using the following sentence template:

Admittedly, at this point our model project has become a little too complex as nobody would organize a team event with these requirements. So, I will give some examples from everyday project experience (for this example, a film database) to make things clearer:

• If the registered user is at least 18 years old, the system MUST give the registered user the option to watch films rated R.
• If the registered user is below 18 years of age, the system MUST hide all films rated R from the registered user. The system CAN give the registered users the option to change their password.
• The system MUST allow the user to enter their date of birth.
• The system MUST be able to verify the date of birth.

You can already see that most of the requirements are clearly described, but that the final one, for example, has leeway in the interpretation of what the verb “verify” actually means. It might signify that the date of birth must have a valid format (MM.DD.YYYY) or that compliance with certain rules should be checked (e.g. date is in the past). These aspects must also be noted.

You may have already recognized that the requirements above present a few challenges: Developers will occasionally still have considerable scope for interpretation. There is some information that might be helpful for the developer - for instance a mockup, an interaction flow and other things. Use cases are therefore a good idea. They describe quite a few aspects of the system and its behavior, especially in regards to its interaction with the end user. I usually write down use cases in a tabular form like we see below, which is actually based on the textbook method:

Although the example again reveals its weaknesses here, the principle should be clear. Use case diagrams can even flesh out the entire project (but that would be too much for this article).