Readable requirements

Note on RE tools:
As well as with MS Word, requirements can, of course, also be documented using Case and RE tools. The approach for successful documentation of requirements described below applies not only to MS Word documents but also to any text that is saved in a tool.

Introduction

Scope of this article

The article concentrates on issues of readability of requirements documents. Issues such as section structures and other specifications for creating requirements are not addressed. The literature already provides sufficient examples for this.

The article itself is also written in accordance with the viewpoints of “Information Mapping”. This means importance was attached to providing the information in such a way that the reader can quickly understand it. Therefore, every user can check at this point whether this article displays good readability and information can be found quickly.

For whom is the article interesting?

The article should be of interest to anyone to whom clear and easy-to-read requirements documentation is important. The “Information Mapping” method is not specific to RE. It can be used for almost any type of documentation. The article should, therefore, also be of interest to readers who do not work in Requirements Engineering.

Project context

As part of Requirements Engineering, T-Systems and Telekom Deutschland create shared documents. Two document types from this context are:

• The “demand specification” – here, functional requirements are described from an IT viewpoint, possible solutions are developed and assessed
• The “solution specification” – a selected solution is described here

In RE projects employees from IT and the functional department usually have to read both types of documents multiple times up until the time of acceptance.

Project task

To optimize the collaboration between T-Systems and Telekom Deutschland, new MS Word templates needed to be created for the specified document types (demand specification and solution specification).

The MS Word templates that had been used until this time were to be replaced as, for one thing, they had proven to be too complex and, for another, changes to the IT processes meant that new section structures were required in the templates.

What in particular should the new templates support?

• A standardized procedure
• A shared understanding of the section content
• A shared understanding of the required level of detail in the individual sections
• Very good readability

Readability saves money!

At Deutsche Telekom, large IT projects are constantly being successfully implemented – regulatory topics such as SEPA, opening up new business models, provision of new Web and app services, etc.

30–50 readers per document
Complex topics generally affect numerous IT systems – and, correspondingly, many employees are involved in the implementation.
Within the Telekom Group, hundreds of employees work every day on creating and reviewing RE documents. Every document consists of 50–300 pages and is read by 30–50 employees – sometimes multiple times.

Savings of at least 250 working hours per review cycle
If 50 employees save 60 seconds per page of reading time on a 300-page document, that adds up to 250 hours of time saved for each review cycle of the document!
Those who wish to use their company’s own billing rate to convert this into an actual figure can see the benefit for themselves. Note: 60 seconds of savings per page are a very low estimation.

The elementary roles when writing documents: “creator” and “reader”

The roles to be considered are those of “creator” and “reader”.

The reader is the multiplier
A document is written once, but read many times.
This means that every minute a reader saves is multiplied by the number of readers.
Typical readers of RE documents at Deutsche Telekom are employees of the functional departments, requirements engineers, system analysts, testers, developers and project managers.

The creator enables the multiplication
The goal must therefore be to enable the creator to write for the reader and in a manner that is very readable – without the use of any tools, Word macros, or similar.

By the way:

• “Read and grasp faster” also means “better understanding and fewer misunderstandings”.
• And: Every creator is also a reader (at the latest when he or she has to read his or her own texts again after a few weeks).

Templates as aids for the creators of documents

The created Word templates should provide the creators of documents with the answers to the following questions (among other things):

• How do I write so that the reader can grasp the content as quickly as possible?
• How do I support the fastest possible “skim reading” of the document?
• How do I even arrive at a point where employees are motivated to read such volumes of text?

Selected methodical approach: Information Mapping

Why have a methodical approach for writing documents?

Everybody wants to document information so that it is easy to read. However, many people find it difficult to implement this objective. They are not aware of what they need to take into account so that a text is easy to understand.

The top goal of many creators of RE documents is frequently “completeness” – take care not to forget anything, quickly write down everything that could be important. This leads to endless sentences and long, completely unstructured sections – complete, at least, but extremely difficult to read.

Experience has shown that employees working in the RE environment, in particular, are happy to accept help with structured writing; after all, the desire to write in a readable manner exists – but how to do it?

• According to which criteria do I structure my text?
• How do I best highlight key information?
• What can be placed together and where do I need a new heading?

Information Mapping lends itself as a method for answering these questions.

What is Information Mapping?

Information Mapping is a method that leads to:

• Documents and e-mails being more clearly structured
• Information in documents being found more easily
• The reader saving a lot of time (without much effort for the creator!)

This method has been taught and distributed for decades by Information Mapping International.
Link: infomap.com/en

What are the benefits?

The advantages of words: word boundaries become visible
Before text	After text
forthe­before­textthe­spaceswere­simply­missedout­andlower caseand­uppercase­writing­ignored	For the “before text”, the spaces were simply missed out and lower case and upper case writing ignored.
Conclusion – Example 1:
We can read much faster if word boundaries can be clearly recognized. Question: Who is prepared to read a text that is written in the “before style”? Answer: Nobody, of course. The response here is “return to sender”, as the “after” is expected.

The advantage of Information Mapping: information boundaries become visible
Before text	After text
… These requirements (and here a clear distinction must be made between their functional and non-functional components) are initially detailed further by the functional department before IT, having been informed by the functional department via e-mail, adds the requirements from the IT viewpoint and presents them to the functional department for review and then acceptance once all the review comments have been integrated and there are no further open questions …	… Requirement types Requirements are to be separated into functional non-functional Collaboration between functional department (FD) and IT FD completes detailed description of the requirements and informs IT by e-mail IT describes the requirements from an IT viewpoint IT presents requirements to FD for review IT organizes a review meeting with FD IT incorporates review results and asks FD for acceptance Prerequisite for acceptance There cannot be any more open questions between FD and IT …
Conclusion – Example 2:
We have to process complex information on a daily basis and the following applies here, too: I grasp information significantly faster if information boundaries are clearly visible. Question: Who is prepared to read a document (or e-mail) that is written in the “before style”? Answer: Today, almost everybody – unfortunately! We dare not (yet) return this to the sender.

Forming information blocks

Information Mapping aims to arrange information in “digestible information blocks” and give it a label (a short heading).

Information types:
The method differentiates between seven different information types for this purpose:

· Process	· Concept	· Structure	· Principle
· Procedure	· Classification	· Fact

Golden rule for the creator:
Information with different information types must never be contained under the same short heading (label).

Procedures for separating information

The key procedures for separating information are:

• Chunking: Creating smaller information blocks
• Labeling: Every information block receives a short, relevant name (label)
• Relevance: Only things that belong together should be together
• Consistency: Never name the same things differently
• Integrated graphics: Tables, illustrations and diagrams should be integrated as far as possible
• Accessible detail: Always adapt the level of detail to the type of document

Make information visible

A key component of Information Mapping is optically highlighting (labeling) information blocks that have been identified once.
You should note the following here:

• Every block receives a heading, known as the label (example here: “Make information visible”)
• Short sentences, no convoluted sentences
• Blocks are optically separated from one another with a line
• Section headings must be made clearly visible

Using the method on example 2 (see above)

Now that we know the key points of Information Mapping, we can look at example 2 (see above) more closely. An analysis of the “before text” shows that there are three different types of information:

• Fact: There are different types of requirement
• Process: There are activities for the functional department and IT that are subject to a sequence
• Principle: There is a key precondition for acceptance

The “after text” was therefore separated into three sections with corresponding headlines. For processes, the steps are numbered – this is one of the possible presentation methods.

Do I need training in Information Mapping to successfully use the method?

The training sessions explain how to recognize information types, how to form blocks and how to best present these (as tables, graphs, lists, etc.).

Participating in method training is, of course, sensible. The methodical approaches presented in this article merely touch on Information Mapping. However, a training session is not absolutely necessary for implementing fundamental changes in documentation.

Experience values:

• Analysts are naturally logically oriented in their work.
  As soon as relevant aids, such as an appropriate format template and a brief guide to the method, were available, the readability of the produced documents improved significantly – not perfectly for “Information Mapping purists”, but certainly significantly better.
• Once users got the ideas of Information Mapping they don’t stick to the method’s details very literally. They intuitively write text which is easier to read.

Project for creating new RE templates:
Experiences and tips

Main goals for “our” RE templates

The following goals were the focus for the project cited here:

• Specification/suggestion of specific formatting standards and aids so that
• readers can grasp the produced documents more easily and
• formatting problems in Word are minimized.
• Specification of the document structure and completion aids so that
• the content to be created is clearly outlined
• everybody can easily orient themselves in documents as a result of the structure, which is always the same

Key information about the project

Roles	Project lead Editorship Project team members (approx. 20 from all areas of the company)
Qualification of those involved	Experienced requirements engineers or their managers, testers
Execution	Four two-day workshops over a period of three months Development of the Word templates between the workshops Creation of a “template guide” with general tips and tricks for using the Word templates and on the topic of “efficient writing” Two review cycles for the Word templates Approval of the Word templates in a concluding workshop
Launch	“Train the trainer” principle: Training selected requirements engineers who represent and teach the use of the templates in their department

Formatting: Keep it simple!

Adhering strictly to the formatting specified by Information Mapping would have been difficult to do in Word and would have led to a loss of acceptance of the template among users.

Sticking strictly to the doctrine would mean always having the label to the left of your text block – so a tabular structure. For one thing, this does not correspond to normal document structures and, for another, consistent documentation in tables in Word is extremely cumbersome.

To keep the formatting as simple as possible, when developing the template we avoided this and instead simply placed the label above the text block – as practiced in this article.

Key criteria when launching Information Mapping formats

The following points were decisive for the successful launch of Information Mapping:

1. Do not change the basic character of existing documents – this leads to unnecessary discussion
2. Ensure that the presentation of information boundaries can be integrated easily and harmoniously into existing documents – it should look appealing
3. Ensure easy handling, for example presenting information boundaries should be as simple as inserting bullet points into the text – otherwise nobody will do it!

Formatting: Improved readability through two simple actions

Two things were added or changed in the existing document templates.

1. Information boundaries are presented through a clearly visible heading (label) and horizontal separating lines (see fig. 2)
2. Section headings are shown inversely so that section boundaries in the document are clearly highlighted (see fig. 2)

Accordingly, a new paragraph format was set up in Word and the existing format template for headings changed. All other specifications regarding formatting of documents – as are generally in place at large companies – remain unaffected.

Key experience regarding “section structures in RE documents”

It is, of course, important not to forget any aspect when documenting requirements. However, that does not mean that every aspect needs its own subsection. This overloads the template and means that, in practical work, many sections are left empty.

Find the smallest common denominator:
It has proven valuable to reduce the section structure to the smallest common denominator. This leads to:

• Streamlined templates
• Concentration on what is important and
• Low training effort

At the same time, the creators of RE documents can extend the section structure if required – with the exception of the main section. This increases acceptance and allows the peculiarities of individual departments to be met.

Common understanding of section content

The section heading alone does not reveal everything about the required section content. To achieve a common understanding of the expected section content, completion notes have been created for every section and subsection and added to the template.

Visual preparation of the completion notes:

• Presentation as a table, 2 columns
• Clearly contrasting colors (see fig. 2)

Visual preparation of the completion notes:

1. Short but clear description of the purpose that the section pursues.
   Note: A brief, meaningful purpose definition certainly led to intense discussion while working on the project. However, once the aim has been defined, the content and examples are generated almost automatically.
2. Short but clear description of the expected content (this is much easier if the aim was defined previously)
3. Good examples of the expected content
4. If necessary, checklists with things that should not be forgotten during consideration
5. Description of templates (if used (see below))

Advantage of the table form for completion notes:
The advantage of completion notes in table form is that all completion notes can be removed with two clicks if they are no longer required.

Use of templates

Some sections allow an extremely structured specification for creating the required content. Here, it makes sense to use tables with fixed column and/or row titles as a template.

Examples for templates in table form:

• Specifications for entering contact persons, i.e. a table with the columns “Name”, “Department”, “Role”, “Contact details”, etc. or
• Description of interfaces
• Description of use cases

Templates are very helpful but here, as with the section structure: do not overload – less is often more.

Summary

Readable requirements are possible

Readable requirements are possible – with an entirely reasonable level of effort and significant time gains for all those involved in the project.

What are frequently lacking are pragmatic aids for REs to document information in a well-prepared manner. If these aids are provided, they are happily used and enjoy a very high level of acceptance.

In this example, the REs became more secure in structured documentation, they were more satisfied with the result of their work and, not infrequently, they received praise from their users.

Using Word templates

The decisive factor when working with MS Word is Word templates that are used as a basis for documenting requirements. These specify the section structure, provide notes regarding the required level of detail and offer help with formatting.

In addition, the Word templates aim to help to absorb information quickly. This should all be done as easily as possible – without the use of tools or macros.

“Digestible information blocks” thanks to Information Mapping

The human eye can take in information significantly faster when it is divided into “digestible information blocks” and these are also clearly highlighted within the document. The appropriate method for this is Information Mapping.

Preparing Word templates for Information Mapping

In Word templates, the formation of information blocks can be supported with new format templates specifically created for this purpose. The formation of an information block consisting of a short heading (label) and corresponding text then requires no more effort then assigning a bullet point symbol for a text section.

Note on Case and RE tools:
This method can also be used in tools. At T-Systems, there is practical experience for this. However, a report on this experience would exceed the scope of this article.

Usable immediately

Information Mapping can be used immediately – particularly in combination with a supporting format template for formatting information blocks.

Save time and money

The reader is the multiplier. A document is written once, but read many times.
Every second that a reader saves is multiplied accordingly.

Deutsche Telekom successfully implements a large number of projects every year with several hundred employees. Significantly improved readability of RE documents saves larger projects several hundred hours of effort per review cycle.

Finally ...

At T-Systems, we are receiving extremely positive feedback regarding the templates. Perhaps this article has aroused your curiosity about our procedure. Do you have questions or feedback? Simply write to me.

Web links

informationmapping.com/en
informationmapping.com/en/shop/books