After laying the foundation for requirements modeling during the last three articles, we will finally look at actual requirements, and how to model them. In particular, this article discusses textual requirements. At a later point, we’ll look at non-textual requirements (e.g. use case modeling).

Templates: Requirements Modeling for Beginners

A surprisingly simply method for modeling textual requirements is the use of text templates. For instance, ISO/IEC/IEEE 29148 recommends this. This standard is called “Systems and software engineering — Life cycle processes — Requirements engineering” and is the foundation for serious requirements engineering. It has already been cited in the last article, as it also provides recommendations for the structure of specifications.

ISO 29148 provides only three templates, which cover the majority of needs. These are shown in the following figure:

The simplicity of this approach makes it so attractive: With very little effort, it has the potential to drastically improve the quality of requirements.

Quality Criteria

Having a template is helpful both to the writers of requirements, as well as the readers. Writers have a good starting place that allows them to write good requirements. Readers will eventually recognize the patterns, which will make it easier to quickly grasp the meaning of requirements.

However, it is quite alright to deviate from the templates if it improves the quality of the requirements. Therefore, these should serve as a recommendation, not a prescription. How the quality of requirements can be measured is also covered by ISO 29148: It contains quality criteria for individual requirements, as well as criteria for sets of requirements, shown in the following tables:

Characteristics of individual requirements

• Necessary
• Implementation Free
• Unambiguous
• Consistent
• Complete
• Singular
• Feasible
• Traceable
• Verifiable

Characteristics of a set of requirements

• Complete
• Consistent
• Affordable
• Bounded

Non-Requirements

Not all the text in a requirements specification belongs to requirements. There will be structural elements like headlines and informational text that creates context. It is important to acknowledge this, but it is also important to make it easy to distinguish requirements from non-requirements. There are many techniques for doing this, which are sometimes tool-dependent. Possibilities include:

• Only assign IDs to text that represents requirements. Some professional tools, like ReqIF Studio, allow this. Others, like Rational DOORS, don’t (and assign an ID to everything).
• Provide an attribute that classifies the the textual element.  A simple classification could consist of requirement, headline and information. A sophisticated classification scheme has been suggested by Cimatti (German Article).
• Use Styles to carry meaning. This is an option when a tool like Microsoft Word is used for requirements engineering.

Pictures

I am a proponent of pictures, as long as they carry the information better than text. For that matter, certain forms of text, like tables, can also be quite useful. When deviating from plain text, it is always important to ask: (1) Is there an added value for doing so? And (2) can the pictures be maintained. In particular, if a UML activity diagram is included as a requirement, it must be possible to update the diagram. Again, there are many ways to accomplish this. But keep in mind that outdated information can be worse than no information at all.

Templates on Steroids

Those who like the idea of using templates should look at those suggested by the Sophist group. They published a booklet in German that provides a set of templates, and a method to apply them. While the booklet is currently not available in English, it at least contains English translations of the templates.

Taking advantage of the Model

The main advantage of using templates as described so far has been requirements of higher quality. But more is possible. Specifically, requirements that follow a template can be used for building a model. The easiest would be to use it to build a glossary: Using the ISO 29148 templates above, a tool could automatically generate a glossary term for each “subject”. A more sophisticated approach could attempt to process the other elements as well.

A larger step would be to built an actual domain model and to integrate it with the text templates. For example, the domain model could consist of UML classes, which would represent the subjects in the text templates. We built a prototype of this idea using a domain model in the Event-B modeling language.

Conclusion

Text templates are a quick way for getting started with formalizing requirements. It takes little effort and has many benefits. But this is just the beginning. In the following articles, we will look at more sophisticated requirements modeling approaches. Some are much more powerful than what was presented here, at the cost of a much steeper learning curve.