The Requirements Engineering Magazine appears quarterly. It is cost free and provides you with up-to-date articles reflecting the activities of the RE and BA community.
Simply sign up for being notified about new issues of the Requirements Engineering Magazine.
You may unregister at any time by sending a mail to firstname.lastname@example.org from the e-mail address which you have registered with.
At the Deutsche Telekom subsidiary T-Systems, Word templates have been created for entering requirements using the “Information Mapping®” method. The templates developed in this manner have found broad acceptance and significantly improved the readability of the RE documents created using them. Readers can now read documents much faster and find information in a targeted manner. Structured completion instructions in the Word templates ensure a shared understanding of the required section content and their level of detail. The chosen approach saves the company several hundred working hours per release cycle. The article describes the success factors of the selected approach and shows that readable requirements can become a matter of course – without much effort for the creators of documents.
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.
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.
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.
As part of Requirements Engineering, T-Systems and Telekom Deutschland create shared documents. Two document types from this context are:
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.
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?
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 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:
The created Word templates should provide the creators of documents with the answers to the following questions (among other things):
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?
Information Mapping lends itself as a method for answering these questions.
Information Mapping is a method that leads to:
This method has been taught and distributed for decades by Information Mapping International.
|The advantages of words: word boundaries become visible|
|Before text||After text|
|forthebeforetextthespacesweresimplymissedoutandlower caseanduppercasewritingignored||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.
Who is prepared to read a text that is written in the “before style”?
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
Requirements are to be separated into
Collaboration between functional department (FD) and IT
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.
Who is prepared to read a document (or e-mail) that is written in the “before style”?
Today, almost everybody – unfortunately! We dare not (yet) return this to the sender.
Information Mapping aims to arrange information in “digestible information blocks” and give it a label (a short heading).
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).
The key procedures for separating information are:
A key component of Information Mapping is optically highlighting (labeling) information blocks that have been identified once.
You should note the following here:
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:
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.
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.
The following goals were the focus for the project cited here:
|Qualification of those involved||Experienced requirements engineers or their managers, testers|
|Launch||“Train the trainer” principle: Training selected requirements engineers who represent and teach the use of the templates in their department|
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.
The following points were decisive for the successful launch of Information Mapping:
Two things were added or changed in the existing document templates.
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.
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:
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.
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:
Visual preparation of the completion notes:
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.
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:
Templates are very helpful but here, as with the section structure: do not overload – less is often more.
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.
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.
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.
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.
Information Mapping can be used immediately – particularly in combination with a supporting format template for formatting information blocks.
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.
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.