In the last two articles of this series, we learned what requirements modeling is in the first place, and why it is a good idea (if done right). We also learned that there is nothing magical about modeling, on the contrary: You may already do requirements modeling without even knowing that you do it.

Modeling the Specification

In this article, we will look at a requirements modeling approach that has been successfully in use for decades: The structure of the requirements document. Or, as introduced last time, the Specification Level. As a reminder: By this we refer to the Specification as a whole. Or, in the context of textual requirements, this would be the requirements document.

We don’t need to reinvent the wheel: In the last article, we already mentioned ISO/IEC/IEEE 29148 (in short, ISO 29148), which – among other things – contains a few document templates. In this series (and also our blog), we’ll talk quite a bit about this standard. Not because it is the greatest thing ever invented, but because it is an international standard that creates common ground. Other goodies in the standard include simple text templates, recommended attributes and activities and tasks.

Different Structures for Different Goals

The correct structure of the requirements depends on the purpose of the specification. ISO 29148, for instance, distinguishes between specification documents for stakeholder (StSR), system (SySR) or software requirements (SRS). The figure below shows the outline for a SySR.

We plan on providing templates for requirements specifications in the ReqIF format in the near future. These can be used with our free tool, formalmind Studio, or any other ReqIF-capable tool of your choice. Sign up for our newsletter, where we will announce it, once it is available.

ISO 29148 SySR Structure

The meaning of the various sections is self-explanatory. However, ISO 29148 provides detailed explanations of every section. There are two major benefits of using a standardized template like this:

1. Once you understand the structure, you’ll be able to quickly grasp other specifications that are writing according to ISO 29148. You will quickly find the information that you are looking for.
2. By looking at each section, you are forced to think about all relevant aspects of your system, and it is less likely that you forget a crucial aspect.

Document-centric Template

The ISO 29148-template is clearly designed with a document in mind. This makes sense, as the majority of specifications today is written in Word or Excel – for better or worse. If Word is the tool to be used, then I recommend to look at the Template from lastenhefteerstellen.de (German, signup required).

The ISO 29148-template can also be used with a requirements modeling tool, like formalmind Studio or Rational DOORS. These are tools that still operate primarily on text, but allow structuring with hierarchies, attributes and traces. Using the template “as is” will work, but tailoring it to the tool’s capabilities can improve the result. For instance, the template separates functional, usability and performance requirements into separate chapters. From a document-centric point of view this makes sense. But once we have modeling-capabilities, there are better ways for doing this. For instance, an enumeration attribute for “requirement type” could be introduced, with the enumeration values functional, usability and performance. This approach would allow requirements to be grouped by context, making the specification easier to read.

Specification-Structures for Models

This kind of high-level structure is not limited to textual documents. For those working with UML- or SysML-Models, The SYSMOD book by Tim Weilkiens (review in German) provides a recommendation for a package hierarchy (see figure).

But what’s inside?

No matter whether in a word processor, a requirements management tool or modeling environment: The structures provided still need to be filled with content. And this content needs to be modeled as well. This is what we will look at in the next article.