Subscribe
Modeling Requirements

How to Model Textual Requirements

Requirements Modeling Series

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:

requirements Templates. From: ISO/IEC/IEEE 29148, Page 11

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.

3 Pingbacks/Trackbacks

  • Pingback: What is a Requirements Model? - Formal Mind GmbH()

  • dsg

    Readers interested in this type of approach may also wish to look at the excellent EARS & EARS+ approach proposed by Al Mavin et al.

    http://starstoroad.com/blog/wp-content/uploads/2012/11/A_Mavin_RE10_EARS_Tutorial_slides_FINAL.pdf http://www.incoseonline.org.uk/Documents/Preview/Preview_Autumn_2013.pdf

    and Jeremy Dicks requirements Boilerplate:
    http://www.integrate.biz/downloads/White_Paper-templating.pdf

    • Hi dsg, great resources, thanks a lot. The first PDF is worth it for the pictures of cell phone damage alone.

  • Eckhard Jokisch

    Great article and easy to read. And I really value your continuous passion to make requirements better.

    And – I strongly disagree with the examples 2 and 3 and also with the templates #2 and #3.
    1. It is not clear to me what the added value of #2 and #3 are. If you follow #1 you are save and done. Only thing I have slight criticism on is to name *one* condition. This should be “at least one condition or a combination of different conditions combined exclusively by logical AND”. But maybe that’s in the next revision of ISO 29148 … . Or maybe your can demonstrate the added value of having three templates instead of one.
    2. Example #2 is quite wrong as “detect” is an action and “at ranges out to 100 nautical miles” is a constraint with the value “100 nautical miles”. A constraint without a value is senseless and a value without a scale is almost always senseless and thus not verifiable/measurable. in #1 example the constraint is “within 2 seconds” with the value “2” and the scale “seconds”. In addition I want to point out that even “detect” is not a verifiable action but a solution. There is no way to verify a “detect” unless you couple the detection with a real action at any output of the system – but then you need to ask “why not take the real action instead of the solution “detect”?

    3. Example #3 is a sentence that makes no sense at all – at least in my understanding of requirements. “pending” as an adjective is undefined. “in which invoices are to be paid” is not covert by any structural element and thus opens the door for any garbage that might want to creep into the requirements. “to be paid” is in passive voice and is a strong indicator for a solution/implementation and it is less then clear who is going to take action – which in turn is irrelevant for the system. There are a lot of real requirements hidden in the last statement. As we both love formalization we should be very careful to not add non-formalized garbage 😉

    • Hello Eckhard,

      Outspoken, as always. 🙂 To my defense (as you noted), the templates and examples are taken directly from ISO 29148, as a screen capture out of the spec! I did not write those. I definitely encourage you to also submit your criticism to ISO directly. I have a contact at ISO, if you’re interested.

      As far as the number of templates is concerned: Whether this makes sense cannot be answered in one sentence (it’s a question of expressiveness). My objective was primarily to cover what’s out there. I am still skeptical that one template is enough, but I am open to counter-examples.

      And of course I am a fan of formalization. And it will certainly be covered here eventually. This is only the forth part of the series on requirements modeling, and I don’t want to scare readers away too soon. So: Stay tuned!

      – Michael

  • Pingback: UML Requirements Modeling – an Introduction - Formal Mind GmbH()

  • Pingback: How to Model a Specification - Formal Mind GmbH()