Requirements specifications in an agile environment

Guest contribution by | 20.09.2021

A pragmatic approach in modern project environments

Salesperson: “The customer has described his wishes to us in this set of slides. So you know what has to be done. In three months I can expect the new product, can’t I?”

Anyone who works in development has probably experienced a situation like this before. Don’t worry: you are not alone. Because what is going wrong here happens several times a week in very many development centres around the world. Wishes for a new product are described and simply thrown into the development teams.

Due to the strong networking of systems, this procedure is no longer state of the art. Inevitably, there has to be more communication and more research. Only in this way can the requirements of the legislators of the respective target countries be considered in addition to the customer’s wishes and the requirements of the in-house production be included. And service requirements for maintainability should not be ignored for a long product life cycle. Failure to meet these requirements reduces the success of the project and therefore represents a glaring risk for the client.

In the value chain of a company, the customer specification and the requirements specification therefore appear – if they are presented correctly. These two documents are a very important part of the development project because they can significantly reduce the project risk. Documented requirements help to understand the scope of the project, to capture boundary constraints and to work out solutions. The result of this procedure is an architecture tailored to the organisational unit, with the help of which the author of the requirements specification can assign the requirements to the development teams in a targeted manner.

What is the requirements specification actually? And what is it not?

A requirements specification has a different function than a customer specification; it is, so to speak, a project’s answer to the customer specification. In this document, the requirements from the customer specification are clarified, they can be rejected, adopted and further refined. The requirements specification is classically available as a “system requirements specification” or, in the agile environment, as a backlog with epics and user stories.

The customer specification and the requirements specification must not be mixed up: The customer specification is the responsibility of the client (customer, sales or product management) and the requirements specification is the development project’s response to it.

Two problems arise when they are mixed:

  1. The possibility of separating desired requirements from requirements to be implemented is lost.
  2. Customer specifications and requirements specifications are often legal components of a contract – if they are not separated, legal problems easily arise.

The requirements specification consists of two parts:

  • The requirements, through which the product to be created is fully described.
  • Proposed solutions in the form of a system architecture that shows how these requirements are to be implemented.

 

Input for the requirements specification

For the creation of the requirements specification, the customer specification is first at the top of the list of possible inputs. Without the customer specification, the development department starts looking for what exactly is required. It serves as the central entry point and provides the description of what the customer wants from the product.

Further inputs for the requirements specification are requirements that are available in-house so that

  • the product can be produced.
  • the service department can carry out maintenance or troubleshooting in the shortest possible time.
  • the intralogistics can manage the variability of the products.
  • the product does not incur high disposal costs at the end of its life cycle.

In addition, legislation may prescribe how products must be produced or configured before they can be sold.

What is the procedure for creating a requirements specification?

Far too often I have seen how requirements specifications are written for weeks and months and then many weeks go by before they are released. This not only delays the realisation of the product, but also causes resentment between sales and product management on the one hand and development on the other.

But how can a requirements specification be created in a pragmatic way? And which tasks have to be completed? I have defined two phases that help to create a requirements specification in a structured and goal-oriented way:

Phase 1: Creating a basis

This phase is used to create an overview from the existing documents, customer specifications and drawings. It is therefore a document analysis in the classical sense. In this phase, look at the documents that are available and find others that are referenced but not on the drives. Work out what the project is about. If it hasn’t already been done, create a system footprint to visually represent the results.

In the course of this research, questions usually arise that you need to clarify with others involved in the project.

Before you start filling in the requirements specification, you create a structure of the document to get an overview of the upcoming content. The last step in this phase is to describe the system context. This will show you which parts need to be worked on and provided by the project team and which are outside the project and will therefore not be considered or implemented.

System Context

Phase 2: Describe the problem

This phase is about deriving the system requirements from the customer or market requirements, as well as analysing the technical boundary constraints and converting them into system requirements as well.

The basis for this are approved customer specifications. The requirements in the customer specification must be evaluated and released so that further processing of the requirements is easier. The evaluation can be done in the same document, but better still in a requirements engineering tool.

With the identification of the system functions, the benefit of the system for the customer is described. A first step in this process is the central field in the system footprint, which was already recorded during the development of the customer specification. Further functions should now be found during the processing of the requirements specification, which support these central functions or work towards them.

With the next step, it is possible to derive the functional requirements from this. Functional requirements describe everything that the system should do. The non-functional requirements follow or are elicited in parallel. It is important to know what type of requirements (functional / non-functional) are involved in the elicitation. A functional requirement for an email programme, for example, would be that a mail can be written and sent. How many mails can be sent at the same time is a so-called non-functional requirement, as it does not describe the functionality itself, but the quantity structure or the performance of the programme.

In short, all requirements that determine the functions of the system and all constraints that describe the technical, functional or organisational limits of the system are recorded.

In order to develop in a goal-oriented and at the same time comprehensible way, it is important to document the origin and background of requirements. This is called traceability. The following advantages result from an existing and maintained traceability:

  • Developers can recognise the reasons for which system requirements were created.
  • Cross-connections and dependencies between subsystems can be discussed.
  • In the case of change requests, it can be determined within a short period of time what effects these will have on the overall system.
  • Conversions without reference to requirements may be too much and are not needed in the system.

 

Traceability
Finally, the requirements specification should be reviewed by short and targeted peer reviews. The feedback is incorporated and then the document is released in a final release review.

Creating a requirements specification with agile methods – how does it work?

A requirements specification does not have to be a static document. It describes, to the best of our knowledge and belief, the current status of the wishes and requirements for a system, nothing more – and nothing less! Translated into agile working, this means: You need an iterative procedure with regular reviews and releases of individual requirements specification versions. The whole thing works freely according to the adapted principle of the Agile Manifesto: Functioning requirements specifications are more important than comprehensive documentation.

How can you proceed in detail? First create a initial state of the requirements specification, ideally with a chapter structure defined in advance. If a structure has proven useful in a previous project or a similar development, it may make sense to use it. Present the first version to your colleagues immediately for peer review, because this way you will receive feedback at short notice, knowing full well that not all requirements are included and described yet. In the meantime, you are already working on the second version. This second version can take into account additional requirements, change requests from customers and new findings from development.

To ensure that the requirements specification contains the results with which those involved in the project can continue to work quickly and produce their own results, it is best to proceed on the basis of the document’s chapter structure and pick out the most important chapters together with those involved. The assessment is ideally done in joint discussions and taking into account the greatest risks in the project. This will give you an order in which the chapters can be filled and quickly provide a benefit.

Once a defined set of requirements and chapters has been processed, the document can be released in a release review. When this is the case is up to you: sometimes a time window is appropriate, sometimes a release after the completion of a main chapter makes sense, and sometimes a defined scope of the document is agreed upon in advance. Either way, you should make sure that the requirements specification is “potentially usable” when releasing it.

The first version of an agile requirements specification does not, of course, have the same level of maturity in terms of content as a requirements specification according to the classic approach in two to six months. But that is not the goal either, because the pragmatic approach is the main focus of an agile requirements specification. With the procedure described, you get a correct, approved requirements specification so that you can quickly go into implementation.

In my experience, working with several runs and different versions of the requirements specification fits wonderfully in an agile environment, especially since the employees in the subsequent trades do not have to wait long, but can start quite quickly with the preparation and the first investigations based on the first requirements specification version. Knowing full well that changes will come.

 

Notes:

If you want to learn more about requirements specifications and the agile approach, listen to the podcast https://zukunftsarchitekten-podcast.de. Bjoern Schorre describes tips and tricks for agile working. If you need help with systems engineering and the creation of a system architecture, take a look at https://bjoernschorre.de.

Bjoern Schorre has published another article in the t2informatik Blog:

t2informatik Blog: Pragmatic interface design of a mechatronic system

Pragmatic interface design of a mechatronic system

Bjoern Schorre

Bjoern Schorre

Dipl.-Ing. Bjoern Schorre is a GfSE-certified systems engineer and the operator of the Ingenieurbüro für Systems-Engineering. With 20 years of professional experience in various industries, he can analyse and optimise development processes as well as assist in the implementation of requirements specifications and architectures. Through his mentoring programme for systems engineering, he passes this knowledge on to medium-sized companies. Bjoern Schorre also helps with concrete topics such as the short-term creation of customer specifications for a new product.