What is requirements engineering and what content goes into a specification?

What is requirements engineering? That question comes up from time to time among people unfamiliar with informatics. When it does I don’t talk about documentation, contracts, or tests, but about communication. As it says in the agile manifesto¹, it’s about people, communication and functioning software, not about contracts, workflows and documentation. That is especially true in requirements engineering. That’s why I like to refer to requirements engineering as a translation activity in my lectures. The requirements engineer is a bilingual translator who turns the user’ explicit desires and implicit needs into a language that the developer can understand so that she can create just the right software. And the reverse is true too: The requirements engineer translates statements and questions by developers into a form that the users can understand and respond to. That is the essence of requirements engineering. Everything else is a supporting act to the main show.

The definition of a requirement

The definition of a requirement according to the CPRE glossary² and IEEE Standard 610³ captures this multi-lingual dimension:

“A requirement is:

1. A condition or skill that is needed by a user (person or system) in order to solve a problem or achieve a goal.
2. A condition or skill that a system or partial system must fulfill or possess in order to satisfy a contract, norm, specification or other documents structured according to formulae.
3. A documented representation of a condition or property as in point 1 or 2.“

The documented representation of a requirement is mentioned explicitly because requirements can also exist and function unconsciously, or even orally. The documentation is a means to an end. The act of writing forces you to make exact formulations and to make decisions. It encourages discussion, leads to the discovery of contradictions and gaps, as well as to the validation and verification of requirements. Misunderstandings cannot be totally avoided but their frequency can be reduced.

Even though agile development reduces the documentation of requirements to user stories in the minimalistic form, the validation and verification of the requirements takes place during the discussion and on the basis of the previous iteration of the IT system. On one hand it is beneficial because it could help you avoid possibly filling papers with bad, misleading requirements – that won’t even apply the following day. But one thing will fall away that is still necessary in complex projects: a feedback system for the user. One which allows you to check if everything has been understood correctly and which provides a feedback loop back to the developer – to check if the requirements are individually executable or if they can be combined with other requirements for a meaningful solution. Eventually a comprehensive, well-thought out concept is necessary.

Professional and technical translation

I think the informational content of user stories is too narrow. What else still needs to be documented? That depends on who you are talking to. The written requirements specifications serve the communication. That’s why every project’s optimal document will look different. It’s important to know who the active participants in the discussion are. If users and developers don’t speak the same language (jargon or graphical notation) then at least two representations of the same requirement are necessary. For example professional and technical concept as well as a requirement specification. Professional requirements need to be translated into technical language and once the changes have been made, back again. Of course the redundancy is not efficient because the same content is held in different languages which constantly need to be kept consistent. Every change needs to be implemented. Unfortunately there is often no one-to-one correlation between chapters because the users structure their requirements according to professional criteria (e.g. user groups or business processes or managed objects) while the developer side is structured according to technical criteria (e.g. IT components). And our translator also requires traceability between chapters or units belonging to both specifications.

Requirements engineering – all about people and communication

You should not have to wrestle with this complexity, it is an indication of the fact that the professional side and developer side can be integrated in order to create a complex IT system. Unless teams have been working together for long enough so that the user side understands the technical language or vice versa misunderstandings can happen in intercultural projects. Alternatively we could try to agree on “simple English” as the common denominator and write a specification in simple notation with minimal vocabulary and simple syntax that fosters understanding between both sides. Which brings us back to user stories that fulfill exactly that purpose.

Towards specification content

We assume that user stories are not enough. When the content and the form of specifications depend on our counterparts, there is no standard template that fits every situation. Which begs the question: “Which content should be recorded in writing?” The tailoring of a template requires an iterative approach with trial and error because general knowledge about the content that is needed does not exist yet. The research has only managed to deliver splinters of information on that subject to date⁴, e.g. about software architects’ information needs⁵.

The following image shows the three possible directions your approach could take:

What content goes into a specification?

1. You can assume a comprehensive standard like ISO/IEC/IEEE 29148⁶ and leave out capital that none of the participants need. The standard is so comprehensive that everything has been thought of that everyone could ever need.
2. Or inversely you start with a minimum, e.g. with the user stories of the agile development and add content on a continuous basis. If you work iteratively then, at the end of every iteration you can determine what was missing. The literature offers many ideas about which notation should be used to represent information.
3. The third approach begins in the middle of a template which has already proven to be of great value: a lightweight template for requirements specifications from a users’s point of view (in German only), based on  my experiences in the field. It can serve as a basis for your own, custom templates; feel free to add or omit individual chapters.

Notes

You can find the specification template by Dr. Andrea Herrmann (available for 4 Euros, in German only) at http://herrmannehrlich.twoday.net/stories/leichtgewichtige-lastenheft-vorlage-zu-kaufen/. It facilitates the creation of lightweight software requirement specifications as texts as well as in graphical representations (e.g. UML) and is suited for functional and non-funtional requirements.  It is the result of continuous simplification and a strong focus on the essence.

[1] The agile manifesto

[2] CPRE glossary at IREB Klaus Pohl, Chris Rupp: Basic Requirements Engineering. dpunkt. Publishing, 4^th edition, 2015, pg 3. In German only.

[3] IEEE Standard 610-1990

[4] Anne Gross, Joerg, Doerr: What you need is what you get!: The vision of view-based requirements specifications, 2nd IEEE International Requirements Engineering Conference (RE), 2012

[5] Anne Gross, Joerg Doerr: What do software architects expect from requirements specifications? results of initial explorative studies, 2012 IEEE First International Workshop on the Twin Peaks of Requirements and Architecture (Twin Peaks)

[6] ISO/IEC/IEEE 29148:2011 – Systems and software engineering – Life cycle processes – Requirements engineering

If you’re interested in supporting requirements engineering with tools, you can find a list of requirements management tools here: https://thedigitalprojectmanager.com/requirements-management-tools/