Chris Rupp, Rainer Joppich 7

Templates – Construction Plans for

Requirements and for More

  

■■ Reviewing numerous rules for each requirement takes an enor-

mous amount of time. Therefore, use our requirement templa-
tes for the documentation of requirements.
■■  How to use the requirement templates is easy to learn. If you
use them, you’re already improving the quality of your require-
ments when writing them down for the first time.
■■  Define process words, terms and all other parts of your re-
quirements bindingly to ensure that all persons involved in the
project speak the same language.
7 Templates

7.1 Linguistic and Philosophic Basis

A quick look back to what we’ve been doing so far to create requirements which meet our
high quality demands.
Only if you are In a first step, we question the stakeholders in-depth about their requirements. Alternatively,
lucky! Do not some sketchy descriptions of the system by a handful of stakeholders or in the form of docu-
count on it. mentation of legacy systems might already exist.
We take all these descriptions and attempt to decompose them into their building blocks
while requesting missing information in order to get to the very essence of the statements. A
very involved and lengthy procedure.
However, there is nothing wrong with this as you will be awarded with high-quality requi-
rements if you scrutinize all of them using the SOPHIST Set of REgulations (see chapter 6
“The SOPHIST Set of REgulations”), no matter whether you use our Set of REgulations
in a constructive or in an analytical way. Nevertheless, you will end up with stylistically
The library completely diverging requirements – particularly if the requirements were not formulated
director’s in the writer’s native language. The following three requirements demonstrate the problem:
requirement During every registration, the customer’s banking details are saved.
If the customer is not registered yet, the librarian should be able to
enter their personal data and the customer will be assigned an unambi-
What the customer guous number by the system.
wants If an unregistered lender wants to lend books, the person
first has to state his or her name, address and date of birth.
After successful registration, the system assigns an ID to
And this is the the new customer and links their data with the unambi-
librarian’s opinion. guous ID.
By the way: We asked three stakeholders about the same situation,
a customer’s registration in the library, and we got three different answers. How could it be
any different!
These answers do not just differ in word order and diction, but also with respect to content.
Probably none of the stakeholder groups will be able to comprehensively describe the issue
in question in all its aspects. Moreover, related words are used which are not necessarily
semantically identical, e.g. customer/lender or to assign/to link.
After all, every stakeholder lives in his own reality. The big question is whether it is possible
at all for these people involved in the project to develop a common and consistent understan-
ding of the system to be.
This problem has been the subject of intense scientific study; from the Sophists in ancient
Greece to Ludwig Wittgenstein and Gottlob Frege to Noah Chomsky and John Searle as well
as many other modern linguists and philosophers. They all struggle with questions such as:
■■  How does language “work“?
■■  What is the innermost nature of language?
■■  How can language be formally described?

2
 Templates 7

■■  In which way do people learn language?

The reassuring
■■  Is communication via language possible at all? answer to this
Our template-based approach is established on these linguistic and philo- last question is:
sophical bases, yet exhaustive explanations of the same would go beyond basically YES.
the scope of this book – and probably bore most readers. For fans of pure
research, linguistics and philosophy we have compiled several articles on
the subject at www.sophist.de/en
“Better“ means: the
We will be focusing on the fact that some requirements are “better”
than others. This provokes the question: requirement already
How can we obtain the best phrasing DIRECTLY? meets certain quality
  criteria, which other
“bad” requirements do
not.
7.2 The Template-Based Approach Our templates are the answer.

Let us show you how to save time and effort while writing high-quality requirements
with astonishingly easy means. We will provide you with templates that help you phrase
requirements and support you in assuring their quality. Using our templates, you instantly This means that
create high quality requirements – thus providing constructive quality assurance. Learn more from the outset a
about quality assurance in chapter 10 “Techniques for Checking Requirements”. row of linguistic
Our primary focus is on the syntax of the optimal requirement. We can thus exclude typical
effects will NOT
mistakes in phrasing, for example passive constructions, which mostly do not provide any in- appear in your
formation on who is expected to perform the specified functionality, requirements.
from the outset.
Using templates when writing requirements leads to all require-
ments having a similar structure. Comparable to a house being
built in accordance to an architect’s plan, each requirement can be
assembled in accordance to a blueprint. We call these syntactic re-
quirement templates, as only the requirements’ syntax (structure) is
stipulated, but not their semantics (content) –section 7.4 delves
into more detail on this.

A requirement template, also called a sentence mold, is a blueprint for the syntactic
structure of a requirement.

Memorize the three requirement templates presented below and instantly start writing your
requirements using them. Our templates are tested and proven and most stakeholders adopt
A kind of deployment
them with excitement, as they are easy to learn and understand. strategy for
templates
In case your stakeholders are rather unwilling, better not try to present our templates to
them. You will probably be more successful if you take your stakeholders by surprise and, for
example, rephrase requirements according to template step by step during review meetings.

3
7 Templates

 7.3 Building the Requirement Step by Step

Have we built up enough suspense? Let’s take a look at the requirement templates and a step-
by-step instruction delineating how to fill all parts of the construction plan with content.

STEP 1:
Stipulate the degree STEP 4:
of legal obligation Identify the object

System‘s name

STEP 2:
Identify the process
STEP 3:
Classify the type of functionality
Figure 7.1: The requirement template without preconditions

Go through steps 1 through 4 for each requirement and fill in the appropriate part of the
template. As soon as you have done this ten or twenty times you will feel you have interna-
lized the template. After writing some more requirements this way, you will automatically
write all your requirements according to template without even thinking.
Let’s do the first requirement together. After that, you will have to practice on your own.
We’ll take the system’s name as a given, as we suppose you know what system it is you are
writing requirements for. In our case, it is a library system. The system’s name is always the
subject, so we can start right off with step number 1.
We choose a legally
binding requirement If your system happens not to have a name yet, you should define one and insert it here. If
and therefore insert you do not want to use your system’s name here, simply write “the system” or, as we have
the modal verb done in our example, “the library system”.
SHALL.
Step 1: Stipulate the degree of legal obligation.

Our first requirement stub.

The library system shall ...

Step 2: Identify the called-for functionality.

4
 Templates 7

The functionality requested is the centerpiece of each requirement (such as: to print, to
save, to transfer, to calculate). We’ll be calling this the „process“ from now on. Processes are
procedures or activities and should exclusively be described using main verbs – the so-called
process verbs. From a grammatical point of view, main verbs play a distinguished role as the
whole sentence (in our case: the whole requirement) revolves around the process verb.
Our first Requirement — as
The library system shall print. a complete sentence (Re-
quirement Bib-001, version 1).
Step 3: Classify the type of the functionality requested.

The system’s activity (functionality) is closely related to the process verb. Attempts to classify
system activities revealed that there are basically three types of activity relevant when writing
requirements:

Autonomous system action: The Interface requirement: The system

system STARTS the process User interaction: The System performs a process DEPENDENT
AUTONOMOUSLY and PROVIDES the user WITH THE ON ANOTHER ENTITY (e. g.
EXECUTES the process auto- ABILITY to do something. another system, but not a user), is
nomously basically passive and awaits an exter-
Figure 7.2: Types of system activity
nal trigger.

Each of those activities can be described with one of our templates (represented by the three
paths through the template in figure 7.1). You may be pondering the question whether a user
interaction requirement is just another type of interface requirement. This is true to a certain
degree, but in an interface requirement, it is of no importance which system docks onto
the interface – with a user interaction requirement on the other hand, there are very often
detailed specifications regarding what kind of system behavior is provided to which group
of users in which way. This is why we created a separate template for user interaction which
enables the person writing requirements to specify this aspect as well..
The library system shall print.
Requirement Lib-001, Version 1: autonomous system action. The system
starts the printing process. In accordance to the template, we do not
need to change anything.

5
 7 Templates
Requirement Lib-002, Version 1: user interac-
tion. The user triggers the printing process.
The library system shall provide the librarian with the ability to print.

Requirement Lib-003, Version 1: interface requirement. An incoming

event from an external system triggers the receiving process.
The library system shall be able to receive data from another library.

The different types of system action

Use palpable role names Type 1: Autonomous system action

like „the librarian”.
The first template is used to construct requirements describing a process
started and performed autonomously by the system. There is no user action.
This is the requirement framework:
THE SYSTEM <name> <shall|shoud|will> <process>.
<process> denominates the process verb chosen in Step 2, for example “print”
for a printing functionality or “calculate” for a calculation performed by the
system.

Type 2: User interaction

If the system provides a functionality that is triggered by the user (like
filling in a form) or if the systems interacts with the user, then require-
ments are constructed using the second template:
THE SYSTEM <name> <shall|shoud|will> PROVIDE
<whom? > WITH THE ABILITY TO <process>.
Write the role of the user the system shall provide with the ability to trigger
The term “user“ is the functionality as the <whom?> into your phrase. The <whom?> is only considered
too general and is optional if it is unambiguous to whom the system provides the functionality. In our
only used if you want templates, we have not marked the <whom?> as optional as its omission would lead to
to express that the a deletion effect. Even if the process is provided to all potential users, we recommend
functionality can be documenting this.
configured for roles.
Type 3: Interface requirement
This template covers those cases when the system per-
forms a certain action only in dependence of another
entity – which is not a user. Please imagine system A
which receives information from another system B
and not from the user. This input can be acyclic and
asymmetric. On reception of messages or data, system
A reacts and performs a process.

6
 Templates 7

Be careful: If there is a type 3 requirement in system A, system B has to have a mat-

ching requirement of type 1 or 2.

Both, type 1 (independent system activity) and type 2 (user interaction), are inappropri-
ate to describe this scenario. Type 2 is discarded as there is no user interaction, and type 1
should not be used as it is an external event that triggers the system to start and perform
the process. We have experienced that the following syntactic construction is suitable:
THE SYSTEM <name> <shall|should|will> BE ABLE TO <process>.

Step 4: Identify the object and additional details.

The examples above show that so far we have produced only stubs of requirements. To
complete these, we need some more parts. In Requirement Lib-001, version 1 there is no
information on WHAT is to be printed or WHERE . Linguists would say: there are objects
and adverbials missing. In simple words, there is a lack of detailed or defining information
about the process verb “print”. In our template, objects and adverbials are inserted at the end
of the sentence. Thus, our requirement looks like this:
The library system shall provide the librarian with the ability to print a library card on the
network printer. Now with object
and additional infor-
Now we already have a requirement of fair quality. However, we can increase the quality by mation: Lib-002,
completing another two steps. First, we can include conditions under which the process is to Version 2
be executed. Second is re-checking the constructed requirement using our SOPHIST Set of
REgulations to discover remaining linguistic effects. These are steps 5 and 6 when creating
requirements with the help of a requirement template.

Step 5: Set down the conditions which determine when the called-for
functionality will be executed.

Typically, the functionality called-for in a requirement isn’t carried out or provided continu-
ally, but rather depends on temporal and logical constraints. In order to clearly distinguish
between temporal and logical constraints, we use the conjunction AS SOON AS to express
temporal conditions. For logical constraints, we habitually use the conditional conjunction
IF. As for temporal conditions, further temporal conjunctions may be used (see paragraph
7.4.4).
Can you imagine how many evenings analysts can spend discus-
sing the question whether "as soon as" and "if" are the only
correct conjunctions in existence?

7
 7 Templates

Conditions are placed in a subordinate clause preceding the actual requirement. Thus, we
expand our example:
STEP 5: Formulate logical
and temporal conditions STEP 6: Apply the SOPHIST
­‚‚ 
Set of REgulations
   
    
 
 ƒ‚  ­€‚ 



ƒ  


€­€‚
 ‚‚ 

Figure 7.3: Requirements template with condition

As soon as the library system has saved the user data, the library system shall provide the
librarian with the ability to print a library card on the network printer.
Requirement Lib-
002, Version 3: The following template-based sample requirements have prefixed conditions:
now with a temporal Example Type 1: Autonomous system action
condition
If the customer data entered is already present in the system, the system shall display the error
message „customer already exists“.
Example Type 2: User interaction
If a customer is not yet registered on the library system, the library system shall provide the
librarian with the ability to enter a customer‘s name and date of birth.
If a customer has not lent any items, the library system shall provide the librarian with the
ability to delete this customer.
Example Type 3: Interface requirement
As long as the library system is in operation, the library system shall be able to receive software
update data from a central administration computer via the local area network.
If you start describing fairly complex processes comprising several steps, you will have to
break the description down into several sentences. Each of these sentences may be construc-
ted using one of the templates. The following example illustrates this:
The library system shall provide solely the administrator with the possibility to import new
media items from external data media into the database of the library system.
If a semantic or syntactic data error occurs during import, the library system shall display the
respective errors (error ID and error description) for every single media item to be imported
on the display and print the respective errors on the printer.
After the library system has received data of newly entered library customers or new media
items from another library system, the library system shall save the received data permanently.

Step 6: Apply the SOPHIST Set of REgulations to your freshly built requirement.

8
 Templates 7

After step 5, every requirement constructed in accordance to one of the requirement tem-
plates has a complete structure. However, the requirement is not perfect yet, as - ignoring
a few exceptions - the semantics are still subject to the requirer‘s creativity. The object and
its additions inserted in step 4 can be chosen at the author‘s discretion. In consequence,
consistency and completeness are solely up to the person writing the requirements. This is
why the occurrence of linguistic effects is possible. To conquer those, apply the SOPHIST Set
of REgulations (see Chapter 6 „The SOPHIST Set of REgulations“) after having assembled
the requirements to perfect the semantic meaning.
If you’ve structured the requirements using a template, the application of the SOPHIST Set
of REgulations will only reveal few linguistic effects, whose removal will be undemanding.
The following examples show requirements that contain an incompletely specified quantifier
(ALL data), although the requirement has been assembled in accordance to template type 1.
On the first day of every month at 8:00 a.m., provided that the administrator has activated You discover the
the automatic backup function, the library system shall automatically archive all data of the quantifier ALL and
library system. need to ask yourself,
"Really all data?"
This enables you to construct an improved requirement:
As soon as the point in time [first day of a calendar month, 08:00 CEST] is reached AND
if the automatic backup function of the library system is activated, the library system shall As a side effect,
automatically archive the data of the library system which has changed since the previous
backup (delta backup strategy).
we also have descri-
bed the conditions in
a more accurate
7.4. Adding Semantic Accuracy to the Requirement Template fashion.
A look at existing requirement specifications reveals that we may have already
come further than many a requirer before us. As you see, a requirement
may contain several condi-
Nevertheless, we have not achieved our goal - a really good requirement - yet. tions as well. Those will
To make the requirement perfect, we need to define its semantic compo- be connected with logical
nents, as the requirement template is only a framework which defines operators. Here it is a
the parts of a requirement and how these parts can be bound together
without redundancies in a consolidated and optimized way. We need
logical AND.
to fill the components with semantics, meaning: with content. We need
to create semantic definitions for the requirement template‘s components
and use logical operators as well as semantically concise expressions. We will show you how
to fill the exchangeable and freely fillable parts of the template with defined terms and words.

Different authors have to choose the same words when describing the same thing or situation. Definitions, like require-
ments, need a degree of
legal obligation.
However, different people will only make the same choice of words if you make sure that
the vocabulary at their disposal is limited and that the meaning of the usable words is clearly
defined.

7.4.1 Legal Obligation

First, you have to stipulate the keywords for the legal obligation of a requirement as well as
the keywords‘ meaning. Usually, a table with two columns is used, which may look like this:

9
 7 Templates

Legal Obligation Keyword

Excursion to testing: All
shall-requirements are
tested. Only implemen-
ted should-requirements
are tested. Will-re-
quirements are not te-
sted.
The term “shall” is used to define legally binding
requirements.
■■ The defined requirement is binding.
■■ The fulfillment of this requirement in the product is shall
binding.
■■ Acceptance of the product can be denied if a shall-
requirement is not fulfilled.
The term “should” is used to define desirable require-
ments. Desires:
■■ are not legally binding.
■■ do not have to be fulfilled. should
■■ help improve collaboration between stakeholders
and programmers.
■■ increase the stakeholders’ satisfaction.
The term “will” is used to define requirements that will
be integrated in the future.

■■ Future requirements are binding. will

■■ They help prepare the system currently being built
for the optimal integration of future functionalities.

Figure 7.4: Definition of keywords for the legal obligation

We have made the
experience that in
most projects only
shall-requirements are
needed.
Add a short explanation, maybe like this:“Requirements have dif-
fering degrees of legal obligation. A requirement‘s legal obligation
is delineated by its keyword. Valid keywords can be found in the
following table.“
  Only describe keywords you really need in your table. Moreover,
explain to your readers what legal obligation means and how the de-
grees are used. As soon as you have your documentation ready, store
it in a central location where every reader and editor of requirements
has it at their disposal. In a requirements specification, integrate
the information on legal obligation into one of the first chapters, for
example the introduction or the reading instructions.

7.4.2 (Process) Verbs

From a linguistic point of view, process verbs are main verbs. They delineate the system‘s
functionality and are therefore a requirement‘s core element. What the author of the re-

10
 Templates 7

quirement is actually requiring must be absolutely undubious to express this functionality

correctly.
Do „insert“, „enter“ and „input“ mean different things in your context? If so, you have to
clearly differentiate between those meanings.
It is important to scrutinize the process verbs and to define them clearly. We’re pursuing the
ideal that each and every author or reader of a requirement understands a verb in exactly the
same way. A means to achieve this goal is a process verb list. In such a list, all main verbs used
in one of your requirements are compiled and defined. This list should be kept in a central
location as well. A good starting point would be to search through all artifacts created during
the first weeks of the project for process verbs.
Take some time off
You can extract process verbs - besides the usual sources of requirements (see chapter 4 „Goals, and write down all the
Informants and boundaries“) - from UML diagrams as well. Activity diagrams verbs in a list!
contain verbs in the name of the diagram itself as well as in the activities‘
names. In a use case diagram, you can find verbs in the diagram‘s name
and also within the use case. State diagrams contain verbs as well: activities
at transitions or triggers describing user interaction or interface capability.
And, of course, you may have verbs in class diagrams. Operations within
the classes or associations can be your sources here.
Expand your list of main verbs to a table with three columns: one
for the verbs themselves, one for their definitions and one for
synonyms. You should also spend some time thinking about
homonyms. Avoid homonyms whenever possible. If you
can’t get around using a homonym in your requirements, you need to
explain clearly which of the meanings of the homonym it is you are referring to.

A SYNONYM is a word with a meaning that is very similar to (or equal with) one
or more words of the same language. To SEND, to TRANS-
MIT, to DISPATCH
something

A HOMONYM is a word that has several different meanings in the same language.
BANK: 1. a place for money
2. a slope
Insert a main verb in every row of the first column of your process verb list. In the second 3. a row of switches
column, you explain the meaning of the verb in your project. Use the third row for synonyms
that exist, but are not permissible for requirements.
You list may look like this:

11
 7 Templates Only these verbs may be Verbs from this column are not
used in requirements. to be used in requirements!

Binding shall-definition: If
you use the process verb "to
display" and your content is
displayed on a side screen
instead of the main screen, Figure 7.5: Process word list
this is a grave error.
The biggest challenge when writing a process word list is undoubtedly the creation of semantic
definitions in the second column. However, we provide you with a template for this as well.
The syntactic construction plan for a process verb:

Figure 7.6: Template for process verbs

As you have already done with requirement templates, fill in all the parts of this template to
get high-quality verb definitions. See Figure 7.5 for examples.
In our examples, we deviate from the template in writing „For the library system“, as we do
not have a palpable system‘s name. If this is the case with your system as well, just reformulate
the way we did.
In a requirements spe- Also make this list available to all the people involved in your project by storing it in a
cification, the list is central location. It may be subject to changes throughout the project duration. However,
usually appended and there should only be few changes if the list was created carefully. You should designate a
person responsible for the maintenance of the list.
referenced to.
Tip: Process verbs are great for reuse. For example: to create, to edit, to save, to archive, to
print, to display and so on. Define your process verbs once, draw a process verb list and reuse
it in future projects. Thus, you can save the effort involved in defining these verbs again and
Do not forget do stipu- again.
late who will assure con-  
sistency between the
process verb list and
your specification.

12
 Templates 7

7.4.3 Nouns - Actors, Roles, Objects and Attributes

Besides inserting information on the legal obligation and the process verbs, you fill the requi-
rement template as well with objects and additional information relevant for the requirement
(step 4). These objects are nouns. In system descriptions, they can be found as objects or
classes, attributes, actors, roles or external systems or organizations. The same rules apply to
nouns as to process verbs; the nouns to be used should be limited and defined unambiguously.
The best way to go is to create a glossary where you list and define the terms relevant to your For further information
project. As a start, a list will do. Creating your glossary works exactly like creating a process on glossaries see chapter
verb list: check all artifacts existing in your project for nouns they contain at an early stage 8 "Documenting require-
and insert those into your glossary. Add semantic definitions and synonyms as well. Use the ments".
following template for writing semantic definitions:

Figure 7.7 Template for semantic definition of nouns

Overall goal: all those
This list of terms - your glossary - assures that all those involved in the project understand a involved in the project
word in the same way, which prevents misunderstandings and fuzziness of communication. speak the same language.
Nouns can not only be found in texts, but also in different semi-formal notations. If you have
used UML, you may find nouns in your diagrams as well:
 In you class diagram, you will find nouns as classes or attributes.
■■  Within activity diagrams, nouns can describe swim lanes or actors. Furthermore, they
can be part of the names of the diagram itself, its activities and the actions.
■■  A use case diagram may contain nouns as actors as well as parts of the use case and the
diagram‘s name.
■■  In a sequence diagram, names of the communicating partners can be a source for
nouns. Another would be names of messages.
Your terminology can also be easily depicted as a conceptual model. Best is a combination of
conceptual model (for structures) and linguistic glossary (for content).
No matter which kind of artifact you are analyzing: as soon as you find a noun, check whether
it is already contained in your glossary. If it is not and if there is no synonym for this term in
your glossary, create a new glossary entry with this term and its definition. In this way, you
constantly expand your terminological world. Of course, a member of your project staff has
to be responsible for the creation and maintenance of the glossary as well. Figure 7.8 shows a
part of the glossary for our library system.

Do not forget to define in which way consistency between glossary and specification will be
assured.

13
7 Templates

Figure 7.8 Glossary with term definitions

Besides all those nouns there are terms which, in fact, should be defined, yet are popular and
common knowledge as society or an institution has defined the term already. An example
taken from our library system is the term „International Standard Book Number“ - better
known as „ISBN“. Include terms like this in your glossary as well. However, keep the expla-
nation simple. The following template will help you:

Use this template

even if a term's
meaning will NOT Figure 7.9 Template for general terms
be defined bindin-
gly. Feel free to include a reference to the official source (an ISO or ANSI standard or simply a
URL). Our example „ISBN“ is included in the glossary in figure 7.8.

7.4.4 Conditions – Logical Operators

Complex systems often only exhibit certain functionalities only if a gamut of conditions has
been met.
You have to define clearly under which conditions the system will offer the called-for
functionality.

14
 Templates 7

An exact formulation of the condition (step 5 in filling in the requirement template) leads
to a uniform structure of requirements. As signal words, we prefix our requirements with
conjunctions. With these, we differentiate between logical and temporal conditions and
define signal words for both types. The different signal words with their definitions can be
seen in figure 7.10. We recommend not to use the signal
word WHEN. It is not precise enough.

Describes a
point in time

Describes
a period
Figure 7.10 Signal words for conditions

If a customer‘s age is less than 18 years,... Examples of conditions with different

After a customer has authenticated himself,... signal words
As soon as the librarian has pushed the emergency stop,...

Excursion: Logical Operators

The logical operators AND, OR and XOR (exclusive OR) are, combined with brackets,
another good means to render the conditions of your requirements more precisely. These
operators will help you if your requirements are often misinterpreted. Have a look at the
following example:
Every Tuesday at 8:00 a.m. or every Friday at 9:00 a.m. and under the condition that at
least ten new customers have been entered into the library system since the last trans-
mission of the new customers statistics, the library system shall automatically transmit
the evaluation data of the new customers statistics to the central administration server.
It is not clear whether the condition that ten new customers must have been entered
only applies to the transmission on Fridays or also to the one on Tuesdays. Moreover, it
is not delineated clearly whether the system shall transmit the data on Tuesdays as well
as on Fridays OR whether the data shall be transmitted only on one day of the week –
which would be either Tuesday or Friday (XOR). Using mathematically defined logical

15
7 Templates

operators makes the requirement unambiguous in terms of the conditions.

(As soon as the point in time [weekday = Tuesday, 08:00 CEST] is reached XOR
as soon as the point in time [weekday = Friday, 09:00 CEST] is reached) AND
if at least ten new customers have been entered into the library system since the last
transmission of the new customers statistics,
the library system shall automatically transmit the evaluation data of the new customers
statistics to the central administration server.
This requirement states unmistakably that a transmission of new customers statistics can
be carried out either on Tuesday or on Friday, but only under the condition that at least
ten new customers have been entered since the last transmission.

You can find more in-

formation on this in
literature dealing with
Boolean algebra.

Figure 7.11: Logical operators for conditions

As long as the library system is receiving data,...

However, logical operators have one disadvantage. One the one hand, they are a great means
to structure complicated requirements clearly, which also makes requirements easier to
understand. Yet on the other hand, logical operators do not improve the requirements‘ rea-
dability. This is the price one has to pay for a high degree of formalization. Deeply interlaced
structures and conditions dependent on one another can only be understood clearly if the

16
 Templates 7

author uses proper formatting.

However, if your textual requirements become too complex or confusing, try using another form
of documentation, like decision tables or structograms.
7.4.5 Abbreviations Does this sound
familiar? People
Last but not least we turn to abbreviations, frequently used in daily communication and in
requirements common as placeholders for any kind of noun – but not understood by many
involved in the pro-
readers. Abbreviations used therefore must be integrated into your glossary and assigned to ject only talk in
a noun. abbreviations and
to you it's all
You should handle abbreviations like all other definitions and keep them as additional infor- Greek?
mation to nouns in your glossary. We recommend adding another column to the glossary:
„abbreviations“. An alternative is creating a list of abbreviations. Be careful: Every abbrevia-
tion hast to refer to a term documented in the glossary. If you come across an abbreviation
Only the abbrevia-
without referenced term, you have to add the term to the glossary. If you want to define tions listed in the
abbreviations that are NOT maintained in the glossary, use this simple template: glossary are permis-
sible for require-
ments.

Figure 7.12: Template for abbreviations

Exemplary excerpt from list of abbre-
viations separate from the glossary
ISBN is defined as International Standard Book Number.
PIN is defined as Personal Identification Number.
BIN is defined as Bank Identification Number.
Of course you can argue that certain abbreviations or terms will surely be understood by
every person involved in the project. So, do you really have to define each and every term,
however clear it may be? Please decide for each case with the following sentence in mind:

If there is only the slightest probability that a reader of the requirement will misunderstand
an abbreviation or a term, you have to add the term or abbreviation with its definition to
the glossary.

Done! There are no further definitions. Using the requirement template and the semantic
definitions, you may now write perfect requirements.

7.5 Experiences made

The templates do not only work for technical systems. They are suitable for every kind of
system. Primarily apply the templates technique when you feel that the project staff would be
willing to use requirement templates.

17
7 Templates

Your requirements authors must not only understand the technique as such but also be willing
to work according to a strictly standardized procedure. The writers‘ degree of stylistic freedom
in constructing requirements will be lowered significantly. We experience the greatest success
if we do not order the requirers to use the template, but train them in using the method and
show them that the templates will help them in fulfilling their tasks. If your authors have to
formulate requirements in a foreign tongue, most people will be thankful for the existence of
templates, glossaries and clear guidelines.
You can introduce
the templates at If you want your requirements to be of highest quality, introduce the templates!
kick-off as well as
at some point during The templates will not only work for IT or software. You can also document requirements in
the project. the fields of hardware, electronics or mechanics using them.
To introduce templates in your organization, compose a four- to six-page document deline-
Do not introduce the ating what templates are about. Illustrate the few curt steps that need to be followed to fill
templates if there the template using an example. This document will then serve as a quick guide for project
are more than ten members. Invite all those involved with requirements to a meeting. There, familiarize them
new techniques in use with the templates and exercise writing requirements using some examples.
within the project.
It is quite all right to let the people
write 20 to 50 requirements.
The first and foremost focus here should be on sentence structure. Then pass out the do-
cument you have prepared and you have completed the first step to introducing templates.
For the review of requirements written according to template you ought to consider the
following: reading dozens of similarly structured requirements can be tiring and requires a
Besides counting lot of concentration. Do not expect anyone to read the entire document in one go. Structure
sheep, reading tem- your document in a fashion that makes it simple for different readers to easily find the parts
plate-based re- significant for them.
quirements is the
best sleep aid.
From now on, assemble your require-
ments and definitions in accordance to
a few simple rules. It‘s as easy as pie!

One last important insight we have gained during projects: make use of software support.
Template-based re- This will simplify your work significantly. The use of requirement templates and a limited,
quirements are best defined vocabulary can be assisted by add-ins/wizards of most requirements management
suited for specifica- tools. By adapting these tools used for documenting and managing requirements to your
tion level 2 and be- needs, you can automate the “construction” of requirements to some extent.
low. However, if you
only specify in level 1,
use templates for
these requirements
as well.

18
 Templates 7

7.6 Let‘s get ready to assemble!

Checklist Templates and Definitions

I have memorized the sentence structure of a natural-language requirement.

I have practiced writing template-based natural-language requirements and it

works out perfectly.

I have understood the template for process verbs and defined my verbs in
accordance to the template.

I have created a process verb list and I will continue maintaining it.
I have placed this process verb list at every involved person‘s disposal.

I have defined terms in accordance to the template.

I have created a glossary with the terms and made it available for all the people
involved in the project. Within the project, there is a person responsible
for the maintenance of the glossary.

I have added abbreviations commonly used in the project to the glossary.

I carefully choose the conjunction to start a condition with.

Due to some practice, I have memorized the different types of templates to

the extent that I automatically write in accordance to template.

19
7 Templates

20