Chris Rupp, Rainer Joppich
Templates – Construction Plans for
Requirements and for More
■■ Reviewing numerous rules for each requirement takes an enormous amount of time. Therefore, use our requirement templates 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 requirements when writing them down for the first time.
■■ Define process words, terms and all other parts of your requirements bindingly to ensure that all persons involved in the
project speak the same language.
7
7 Templates
7.1 Linguistic and Philosophic Basis
Only if you are
lucky! Do not
count on it.
A quick look back to what we’ve been doing so far to create requirements which meet our
high quality demands.
In a first step, we question the stakeholders in-depth about their requirements. Alternatively,
some sketchy descriptions of the system by a handful of stakeholders or in the form of documentation 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.
The library
director’s
requirement
What the customer
wants
And this is the
librarian’s opinion.
However, there is nothing wrong with this as you will be awarded with high-quality requirements 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
completely diverging requirements – particularly if the requirements were not formulated
in the writer’s native language. The following three requirements demonstrate the problem:
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 unambiguous number by the system.
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
the new customer and links their data with the unambiguous 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 understanding 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?
■■ Is communication via language possible at all?
Our template-based approach is established on these linguistic and philosophical bases, yet exhaustive explanations of the same would go beyond
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
The reassuring
answer to this
last question is:
basically YES.
“Better“ means: the
requirement already
meets
certain quality
How can we obtain the best phrasing DIRECTLY?
criteria,
which other
“bad” requirements do
not.
Our templates are the answer.
7.2 The Template-Based Approach
We will be focusing on the fact that some requirements are “better”
than others. This provokes the question:
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
create high quality requirements – thus providing constructive quality assurance. Learn more
about quality assurance in chapter 10 “Techniques for Checking Requirements”.
Our primary focus is on the syntax of the optimal requirement. We can thus exclude typical
mistakes in phrasing, for example passive constructions, which mostly do not provide any information on who is expected to perform the specified functionality,
from the outset.
This means that
from the outset a
row of linguistic
effects will NOT
appear in your
requirements.
Using templates when writing requirements leads to all requirements 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 requirement 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
them with excitement, as they are easy to learn and understand.
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.
A kind of deployment
strategy for
templates
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 stepby-step instruction delineating how to fill all parts of the construction plan with content.
STEP 1:
Stipulate the degree
of legal obligation
STEP 4:
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 internalized 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 choose a legally
binding requirement
and therefore insert
the modal verb
SHALL.
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.
If your system happens not to have a name yet, you should define one and insert it here. If
you do not want to use your system’s name here, simply write “the system” or, as we have
done in our example, “the library system”.
Step 1: Stipulate the degree of legal obligation.
The library system shall ...
Our first requirement stub.
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.
The library system shall print.
Step 3: Classify the type of the functionality requested.
Our first Requirement — as
a complete sentence (Requirement Bib-001, version 1).
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
system STARTS the process
AUTONOMOUSLY and
EXECUTES the process autonomously
User interaction: The System
PROVIDES the user WITH THE
ABILITY to do something.
Figure 7.2: Types of system activity
Interface requirement: The system
performs a process DEPENDENT
ON ANOTHER ENTITY (e. g.
another system, but not a user), is
basically passive and awaits an external 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 interaction. 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
like „the librarian”.
Type 1: Autonomous system action
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 requirements are constructed using the second template:
THE SYSTEM <name> <shall|shoud|will> PROVIDE
<whom? > WITH THE ABILITY TO <process>.
The term “user“ is
too general and is
only used if you want
to express that the
functionality can be
configured for roles.
Write the role of the user the system shall provide with the
ability to trigger
the functionality as the <whom?> into your phrase. The <whom?> is only considered
optional if it is unambiguous to whom the system provides the functionality. In our
templates, we have not marked the <whom?> as optional as its omission would lead to
a deletion effect. Even if the process is provided to all potential users, we recommend
documenting this.
Type 3: Interface requirement
This template covers those cases when the system performs 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 matching requirement of type 1 or 2.
Both, type 1 (independent system activity) and type 2 (user interaction), are inappropriate 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 we already have a requirement of fair quality. However, we can increase the quality by
completing another two steps. First, we can include conditions under which the process is to
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.
Now with object
and additional information: Lib-002,
Version 2
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 continually, 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 discussing 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
Requirement Lib002, Version 3:
now with a temporal
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.
The following template-based sample requirements have prefixed conditions:
Example Type 1: Autonomous system action
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 constructed 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 templates 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
the automatic backup function, the library system shall automatically archive all data of the
library system.
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
automatically archive the data of the library system which has changed since the previous
backup (delta backup strategy).
7.4. Adding Semantic Accuracy to the Requirement Template
A look at existing requirement specifications reveals that we may have already
come further than many a requirer before us.
Nevertheless, we have not achieved our goal - a really good requirement - yet.
To make the requirement perfect, we need to define its semantic components, as the requirement template is only a framework which defines
the parts of a requirement and how these parts can be bound together
without redundancies in a consolidated and optimized way. We need
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.
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.
You discover the
quantifier ALL and
need to ask yourself,
"Really all data?"
As a side effect,
we also have described the conditions in
a more accurate
fashion.
As you see, a requirement
may contain several conditions as well. Those will
be connected with logical
operators. Here it is a
logical AND.
Definitions, like requirements, need a degree of
legal obligation.
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
Excursion to testing: All
shall-requirements are
tested. Only implemented should-requirements
are tested. Will-requirements are not tested.
Keyword
The term “shall” is used to define legally binding
requirements.
■■ The defined requirement is binding.
■■ The fulfillment of this requirement in the product is
binding.
■■ Acceptance of the product can be denied if a shallrequirement is not fulfilled.
shall
The term “should” is used to define desirable requirements. Desires:
■■ are not legally binding.
■■ do not have to be fulfilled.
■■ help improve collaboration between stakeholders
and programmers.
■■ increase the stakeholders’ satisfaction.
should
The term “will” is used to define requirements that will
be integrated in the future.
■■ Future requirements are binding.
■■ They help prepare the system currently being built
for the optimal integration of future functionalities.
will
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 differing 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 degrees 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.
You can extract process verbs - besides the usual sources of requirements (see chapter 4 „Goals,
Informants and boundaries“) - from UML diagrams as well. Activity diagrams
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.
Take some time off
and write down all the
verbs in a list!
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 TRANSMIT, 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
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,
this is a grave error.
Verbs from this column are not
to be used in requirements!
Figure 7.5: Process word list
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 specification, the list is
usually appended and
referenced to.
Also make this list available to all the people involved in your project by storing it in a
central location. It may be subject to changes throughout the project duration. However,
there should only be few changes if the list was created carefully. You should designate a
person responsible for the maintenance of the list.
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
again.
Do not forget do stipulate 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 requirement 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
project. As a start, a list will do. Creating your glossary works exactly like creating a process
verb list: check all artifacts existing in your project for nouns they contain at an early stage
and insert those into your glossary. Add semantic definitions and synonyms as well. Use the
following template for writing semantic definitions:
Figure 7.7 Template for semantic definition of nouns
This list of terms - your glossary - assures that all those involved in the project understand a
word in the same way, which prevents misunderstandings and fuzziness of communication.
For further information
on glossaries see chapter
8 "Documenting requirements".
Overall goal: all those
involved in the project
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 explanation simple. The following template will help you:
Use this template
even if a term's
meaning will NOT
be defined bindingly.
Figure 7.9 Template for general terms
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,...
After a customer has authenticated himself,...
Examples of conditions with different
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 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.
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 information 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‘ readability. 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
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
readers. Abbreviations used therefore must be integrated into your glossary and assigned to
a noun.
You should handle abbreviations like all other definitions and keep them as additional information 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 abbreviation hast to refer to a term documented in the glossary. If you come across an abbreviation
without referenced term, you have to add the term to the glossary. If you want to define
abbreviations that are NOT maintained in the glossary, use this simple template:
Figure 7.12: Template for abbreviations
Does this sound
familiar? People
involved in the project only talk in
abbreviations and
to you it's all
Greek?
Only the abbreviations listed in the
glossary are permissible for requirements.
Exemplary excerpt from list of abbreviations 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
You can introduce
the templates at
kick-off as well as
at some point during
the project.
Do not introduce the
templates if there
are more than ten
new techniques in use
within the project.
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.
If you want your requirements to be of highest quality, introduce the templates!
The templates will not only work for IT or software. You can also document requirements in
the fields of hardware, electronics or mechanics using them.
To introduce templates in your organization, compose a four- to six-page document delineating what templates are about. Illustrate the few curt steps that need to be followed to fill
the template using an example. This document will then serve as a quick guide for project
members. Invite all those involved with requirements to a meeting. There, familiarize them
with the templates and exercise writing requirements using some examples.
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 document you have prepared and you have completed the first step to introducing templates.
Besides counting
sheep, reading template-based requirements is the
best sleep aid.
Template-based requirements are best
suited for specification level 2 and below. However, if you
only specify in level 1,
use templates for
these requirements
as well.
18
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
lot of concentration. Do not expect anyone to read the entire document in one go. Structure
your document in a fashion that makes it simple for different readers to easily find the parts
significant for them.
From now on, assemble your requirements 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.
This will simplify your work significantly. The use of requirement templates and a limited,
defined vocabulary can be assisted by add-ins/wizards of most requirements management
tools. By adapting these tools used for documenting and managing requirements to your
needs, you can automate the “construction” of requirements to some extent.
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