A Gentle Introduction Of A Requirement Syntax

Requirement documentation is mainly done in either Natural Language (NL) or in formal models like UML or SysML. NL offers the lowest learning curve and the most flexibility, which for many companies means: “Everyone can start writing requirements without formal training”.

In contrast, formal modelling languages require a considerable effort to learn and are very restrictive. But, the flexibility of NL comes with ambiguity and inconsistency. These are two major downsides that formal modeling languages aim to eliminate.

Our customers often ask: “Is there something in the middle, keeping the benefits of NL, but reducing the downsides?” our answer: “Yes, a requirement syntax”.

But what has that children’s puzzle to do with writing requirements?

In this blog post we will cover the following topics:

• What makes a Requirement Syntax so attractive?
• What is meant by a Requirements Syntax?
• Why should you use a requirements syntax?
• How do you develop your own Requirement Syntax?
• A great of-the-shelf Requirement Syntax: EARS!
• How to introduce a syntax to your teams?

What makes a requirement syntax so attractive?

Our customer experience the following requirement engineering pains:

• Inconsistent requirements, in both wording and structure.
• Authors feel lost and want more guidance.
• The reviewing process takes too long and doesn’t increase the quality.

In our opinion, if you do not want to adopt a formal modelling language, a requirement syntax offers a suitable remedy for the listed pains.

What is meant by a Requirements Syntax? An unscientific intro to Requirements Syntax Theory

A requirement syntax is a set of rules that modifies and restricts the existing syntax your favorite language (i.e. English) to a subset of valid sentences and words.
For example, instead of letting the author use any valid English sentence for a requirement like this one:

• “The boomblaster 3000 or radio must reflect our corporate identity (we love the band Queen), hence, if it has a internet connection that works: start blasting Queen – The Show must go! “

Right…. Let us limit the sentence to the following structure:

• The <system name> shall respond to <trigger> with <action>.

Using our structure, the same requirement must be phrased as:

• “The radio shall respond to a active internet connection with playing Queen – The show must go on. “

Sounds easy, doesn’t it`?

In short, a requirement syntax forces the author to put the same type of information on the same place, using the same expression. By creating a syntax you basically create prearranged sentences with holes in them. Those holes get a description, describing what kind of information they can hold, and how you should write it.  You can view it as those wooden puzzles children play with. You can only put the crocodile in his dedicated place, not where the lion lives.

The difficulty with a requirement syntax is the creating the right sentence structure.  A good syntax has the correct amount of defined sentences. For an author the difference between guidance and frustrating is the availability to choose the type of sentence. If an author cannot use the syntax because the required sentence structure is not there, it  will become a frustrating experience.

Wait, we just explained that natural language has this lovely freedom! And now we are saying that a syntax can also be frustrating, why use one on the first place?

Why should you use a requirements syntax?

By limiting the vocabulary and enforcing a fixed sentence structure a requirement syntax certainly improves the consistency and reduces the ambiguity in requirements. The predetermined sentence structures and word choices aids the author with focusing on the more important aspects of a requirement: that it is correct, not how to write.

So by using a requirement syntax your huge collection of requirements will: look the same, read the same and the authors are not lost in the process.

Awesome, so how is a syntax developed?

How to develop your own RS

There are to ways to start the development of you own personal requirement syntax. One, you start from scratch. Two, you start with an existing pre-defined syntax. If you want to start with an existing syntax there is no better place than to start with EARS: see the section “A great of the shelf Syntax”.

If you want to develop your own syntax, follow the following steps:

1. Group similar existing requirements.
2. Give the group a name.
3. Create a sentence structure that captures the similarities.
4. Test by rewriting.

By using these steps you create the sentence structures that are actively used, so you automatically create the correct requirement types. No more and no less!  Here, assume we have a number of requirements that express something like:

• If this happens, this is the response.
• When an this event occurs, act like this.
• Do this if that happens.

We give the group a name “trigger-response-requirement” and see that the similarities are a trigger and a response.  We now add the obligatory elements of a good requirement, namely the system name and the imperative (shall, should, will, etc.). With those elements, I would try a sentence structure like this:
The <system name> shall respond to <trigger> with <response>.

The last step, test by rewriting, you can try yourself. Just find some requirements with a trigger an response and see if it works. Let me know how it went!

How to document a syntax?

A syntax has to be self-explaining. In order to achieve that you should document the syntax in a visual manor. A good way of visualizing a syntax is via a syntax graph or also called syntax diagram. Here is an example of a syntax graph: the blocks with “<..>” are those areas of the requirement the author as to define.

Another option is to visualize the patterns with just text. The textual equivalent of the syntax depicted above looks like this:

Use Case: The <system name> shall|should|will support <use case>
Example: The radio should support user registration.

Response: The <system name> shall|should|will respond to <response trigger> with <response action>.
Example: The radio shall respond to an active internet connection with playing Queen – The show must go on.

What is easier? We prefer the syntax graph.

A great of-the-shelf syntax: EARS

There are several actively used requirements syntax’s. Our favorite is: EARS [’09 Paper, ’10 Further Studies]  “Easy Approach to Requirement Syntax” it is lightweight easy to learn and covers most of the needs of our customers. Let me give you two examples out of the five requirement types in EARS:

Event-Driven: When <optional precondition> <trigger>, the <system name> shall <system response>.
Example: When an internet connection is detected, the radio shall start playing Queen – The show must go on.

State-Driven: While <precondition(s)>, the <system name> shall <system response>.
Example: While the user is logged in, the radio shall sent usage reports to the backend system.

See? Easy! EARS offers three more patterns (optional, unwanted and ubiquitous requirements) and that’s it. Sure, it takes much more thinking to master this approach but as an author, you only have to think about what goes in between the <..>.

Now you have a basic understanding of what a requirement syntax and how it works. But how do you introduce a syntax into a team of authors?

How to introduce a Requirements Syntax?

People learn how to write in primary school. Hence, when you introduce a new way of writing, you need some finesse or in German “Fingerspitzengefühl”.  There are three main areas of focus during the introduction of an existing of-the-self syntax:

1. Customize
2. Train
3. Make people happy

When you customize an existing syntax, you can make your good syntax great. Customizing a syntax means to overlay your context. Because an existing syntax is developed without your specific needs in mind,  it becomes your job to put them in. This means mostly that you alter the description of the syntax elements (like <trigger> or <response>) so your authors know exactly what is required. In addition, it’s likely that you have to modify a certain sentence pattern to fit your needs.

After the customization, you should invest the time and effort to train your requirements authors. Using a syntax without proper training leads to frustration. Frustration will lead to a low acceptance of the syntax and therefore to a waste of effort. The training provides the perfect opportunity for trainees to express feedback and to identify potential problem areas. Take this feedback and incorporate it in to the syntax.  Consider your syntax as not done. This also helps in making and keeping people happy.

What we observe is that authors – who were previously struggling and did not enjoy writing requirements – now take pride in their requirements. For example, last Christmas I received a Christmas card from a customer written in the a syntax we developed. How cool is that?

TL;DR

Requirement syntax’s or also called requirements patterns are right on this cozy spot in the middle between the freedom of natural language and the strict control of formal modeling languages.

If you want more structure in your requirements, more guidance for requirements authors and a simple approach that improves your reviewing, Requirements Syntax might be your thing. Contact me, if you would like to know more.