Requirements Engineering - Documentation

Requirements Engineering

Documentation of requirements

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)
Good vs. bad requirements
Figure 1: Good vs. bad requirements; Source: SoftwareONE

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:

Sentence template for requirements
Figure 2: Sentence template for requirements; Source: SoftwareONE

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:

Sentence template examples for requirements
Figure 3: Sentence template examples for requirements; Source: SoftwareONE

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.

Use Cases for Improved Process Design

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:

Identifier Explanation Example
ID Unique identification of the use case UC-0017
Name Name of the use case Go-karting
Priority Priority Medium
Author Originator of the use case Team leader
Source Origins of the use case Stakeholder interviews
Owner Owner of the use case Team leader
References References to other use cases or elements UC-0016
Description Brief description of the use case Go-karting with qualifying and race
Stakeholders Stakeholders within the use case Participants (team members and leader), team event (system), track owner
Trigger Trigger of the use case Notification to the Go-kart track
Preconditions Conditions that need to be satisfied prior to occurrence of the use case All team members and the team leader are present
Go-kart track open and paid for
Main scenario Scenario that is mainly performed 1. The track owner instructs the participants
2. The track owner hands out necessary clothing
3. The participants get changed and pick a go-kart
4. The track owner starts qualifying
5. The participants complete qualifying
6. The track owner ends qualifying
7. The track owner starts the race
8. The participants complete the race
9. The track owner ends the race
10. The team leader presents the certificates
Alternative scenarios Scenarios that could be performed as alternatives to the main scenario A1
3. There are not enough available go-karts
4. The track owner obtains sufficient numbers of go-karts
5. Continue with point 4 of the main scenario
Exceptional scenarios Scenarios that are exceptions and lead to ending of the use case. They can also apply to alternative scenarios. E1
8. A participant has an accident
9. The track owner stops the race
10. The team leader travels to the hospital with the team member
Subsequent conditions Conditions that must be met before the use case comes to an end All participants (team members and leader) have crossed the finishing line
Results Results of the use case, depending on the scenario All participants have received a certificate and are happy
A1: All participants have received a certificate and are happy
E1: All participants travel to the hotel and wait for feedback

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).

Summary: Documentation and Reality

You can spend quite a lot of time documenting requirements to obtain a catalog that describes the system comprehensively and in detail. However important this is for the success of a project, there may not always be enough time. That's why I will use another post to deal with the reality on the ground and how a few compromises can help to implement requirements engineering in IT projects. You have something to look forward to!

Looking for Support With Your IT Project?

Would you like individual advice, or do you have questions about project management in your company? No problem. We are happy to assist you.

Contact Us

Comment on this article

Leave a comment to let us know what you think about this topic!

Leave a comment

Author

Henrik Krumbholz

Senior Consultant

Microsoft SharePoint

Related Articles

Resolving SAP Downtime & Visualization Challenges with PowerConnect & Splunk
  • 24 November 2020
  • Warwick Chai
  • Digital Transformation, Managed Cloud
  • SAP

Reduce SAP Downtime & Visualization of SAP Telemetry

It’s difficult to investigate failures in SAP to prevent them from happening in the future. Find out how to gain SAP intelligence via PowerConnect and Splunk.

5 Tips to Engage Your Audience in Presentations
  • 12 November 2020
  • Future Workplace, User Productivity
  • Microsoft 365, Teams, Collaboration

5 Tips for Remote Presentations

In remote presentations, you’re not only competing for the audience's attention, but also missing their nonverbal clues. Here are 5 tips on how to deal with it.

The Bridge to the Hybrid Cloud

VMware Cloud on AWS: The Bridge to the Hybrid Cloud

VMware Cloud on AWS is the easiest and fasted way to get to the cloud. The solution forms a bridge between local data centers and the cloud.