Why doesn't anyone stick to text templates for requirements?

Text templates for requirements have been around for a long time. The concept is simple: a handful of text templates can be used to express all conceivable requirements. Using the templates results in well-formulated, high-quality requirements.

However, in an industrial environment, their use is the exception rather than the rule. The reason is not hard to guess: Text templates bring many advantages in the long term, but make more work for the author in the short term and restrict the creative workflow. The following is about the effort and benefits of templates and a few pragmatic ideas from practice.

A personal request: I am looking for requirements experts, product developers and product managers for a short interview. The question: How would the automatic processing of natural language requirements help you? You can enter an appointment directly in my calendar here >>. My goal is to better understand the challenges of this target group. Thank you very much!

What text templates are available?

There is an own standard ISO/IEC/IEEE 29148:2018 for requirements management and engineering. In this standard (or its predecessors), templates have been mentioned with examples for at least 15 years. Here is an example from the somewhat older 29148:2011:

In German-speaking countries in particular, the Master templates of the company Sophist are well known. Sophist has published a small booklet that describes these templates and their application in detail. I would particularly recommend this for German-language requirements, as the English formulations in the booklet appear to have been inserted as an afterthought.

The 5th edition of the booklet is 50 pages long. And this is also (partly) the reason why not all requirements are now formulated using templates.

Strengths and weaknesses of text templates

Reading requirements written with templates is no problem. However, it is not so easy to write good requirements. We must not forget that the initial requirements in particular come from a large number of stakeholders. For experts, e.g. requirements managers, it is absolutely fine to deal with writing requirements. But we cannot expect this from most stakeholders. So when they formulate the requirements themselves, they come in the form of e-mails, Word and Excel documents, flipchart pages, PowerPoint and many other forms. But very rarely formulated according to a template.

However, template-based requirements have enormous added value if they are applied correctly. They have many quality features of their own: They are unambiguous, atomic and precise. But the effects only manifest themselves during development. And as with many things that have a preventative effect, almost nobody notices their presence. The problems are noticed when they are absent. And even then, the team does not necessarily identify the poorly formulated requirements as the cause.

3 ways out of practice

Now that it has been clarified that templates bring an advantage, we must not only enable their use but also demand it. In the following, I present three possibilities that I have successfully observed in an industrial environment:

If the authors of the requirements are primarily experts who work in a clearly defined domain, they will quickly recognize the value of templates. It is also possible to make the templates domain-specific. I experienced this, for example, at an automotive supplier that had been formulating a specific component based on templates for many years.

The manufacturer created its own library of templates (over 100) that were precisely tailored to the domain. He also had to deal with a large number of variants, as each vehicle model required a customized variant. The templates drastically saved time, ensured consistent behavior in all variants and increased quality at the same time.

In the Modeling text templates are also often used. Templates for use cases and user stories, for example, are very common. Here is the template for user stories:

"As I would like to "

Text template for user stories

I have described another example in detail in a specialist article in RE-Magazine: Modeling Requirements with Constraints. These two examples clearly show that templates help on the way to the model, regardless of whether they are lightweight (user stories) or semi-formal (RE magazines).

Finally, we have the option of deriving clean template-compliant requirements from the initial requirements (e-mails, flipcharts, etc.). The advantage is obvious:

• Stakeholders can formulate their requirements using the tools of their choice.
• The template-compliant requirements enable clean, traceable development of the product.
• With traceability between stakeholder requirements and template-compliant requirements, stakeholder input can be validated systematically and comprehensibly.

Here is an example: Stakeholder input on the left, two template-compliant derived requirements on the right:

Traceability to the original requirements is very important, because content has been lost on the right-hand side ("Google-focused"). Although this is not a requirement, but context, it is still relevant in order to understand the motivation behind the requirement.

The advantages of this approach are offset by considerable additional expense. Whether the effort is justified depends on the added value that the organization can derive from it.

Tool support

There is more or less helpful tool support for the approaches shown here. First of all, tools that help with template-based input have been around for decades. For example, almost all requirements management tools allow initial content to be stored in text fields. A text template can then be stored there as free text, which the author then edits like normal text.

Form-based editors that provide corresponding form fields for free text are more sophisticated. I don't know anyone who likes using these systems: The form fields disrupt the reading flow, simple functions such as cut & paste are a pain with many systems. The result is good, but many users are frustrated.

I find the approach of allowing free text but still processing it automatically, as is now standard with source code editors, interesting. Here is an animated example, even if templates are not actually used:

Unfortunately, these approaches are already too technical for many stakeholders.

Machine processing

In addition to the editors, there are tools that analyze the requirements. I would find it very interesting if a system could automatically generate the derived template-based requirements. However, I am not currently aware of such a system. The most similar is the Research work by Arora et.al., in which a domain model is automatically derived. It would be exciting to have a system that automatically derives requirements as shown in point 3.

I am currently supervising a Master's student with this topic. I would therefore be pleased about direct feedback whether such a system would be useful for you. It would also be helpful if you could answer the survey in the right-hand column (if you haven't already done so).

Conclusion

Even if templates are undoubtedly useful, they come at an additional cost. Here it helps not to demand the templates across the board, but to examine exactly how high the expected added value is (quality) and whether the effort is worthwhile. The more specific the use of the templates is and the easier it is for stakeholders to understand the added value, the more sensible it is to use them.

I am actively researching this topic with a student and am happy about direct feedback.

Photo by Ryan Fields on Unsplash