Documentation has existed since applications were written and operated: project documentation for development and operational documentation for the ongoing operation of applications. Their creation is an unpopular activity, which is gladly postponed or sometimes omitted entirely because the budget has already been used up. All of us know how important documentation is – for example, when applications are transferred from one service provider to another or when new employees want to familiarize themselves.
Photo: Alexander Supertramp – shutterstock.com
Documentation, especially of large, grown, business-critical systems are often in a deplorable state. In our experience, keeping it up-to-date takes an average of five to ten percent of the total expenditure on development projects. Most of those responsible for business-critical applications will – when asked about the quality of the documentation – answer: “not sufficient”. So if the documentation is bad, but important and above all expensive, how can it be improved? Companies can start with WAS and HOW.
An application always has two types of documentation: permanent documentation, which shows the entire application in its current state, and temporary or project documentation, which describes a change.
The permanent documentation is a static reference for the application. The aim of the temporary documentation is to support the creative and collaborative process of development. It is clear from these different goals that one documentation cannot fulfill the purpose of the other at the same time.
Permanent documentation is used, for example, for the following tasks:
-
Business process that the application supports
-
Functions / professional entities,
-
Requirements in regulated environments,
-
Context diagram / component diagram,
-
technical architecture,
-
Regression tests,
-
Operating manual,
-
User Guide.
Temporary documentation is used when the following tasks are involved:
-
Requirements / user stories,
-
Specifications / specifications,
-
Design / technical specification,
-
Database model,
-
Class diagram,
-
Test cases, test documentation.
-
Release notes.
There are two approaches to document the current status of the application. On the one hand, permanent documentation can be the collection of temporary documents. This saves time in the creation, but is illegible in the long run: if the reader wants to know why a function is as it is, he has to read the entire documentation backwards until he finds the document describing the installation of this function .
In the other variant, the permanent documentation is updated after each change is completed. For this purpose, only permanently relevant information is taken from the temporary documentation. This is complex, but easier to read.
How the documentation is stored is also important for the HOW. This usually happens in the form of different documents (for example in Word) on a common platform such as SharePoint. This brings together a large number of documents that are easy to edit collaboratively, but the documents are difficult to search, are not linked to one another and their version may not be up to date.
However, these aspects are particularly important for modern and future-proof documentation. It is about good searchability, linking (for example between test cases and requirements and between diagrams and prose texts that describe them) as well as version security. It is also in the interest of the developers to document little overall, to concentrate on the essentials and to make do with just a few documents. How can this be achieved?
In our view, the essential elements of good, permanent documentation are:
-
A brief description of the application functions: What does the system do? Which business process does it support? What functions does it offer? This description of the technical requirements can be purely textual. In addition, a technical entity diagram is recommended, and a context diagram is also helpful.
-
The list of requirements that belong to the available functions is also important. It can be used to understand why a certain function is needed.
-
A description of the technical architecture that is limited to the essentials is also indispensable: How is the system structured? Diagrams are particularly useful here: context diagrams, component diagrams and illustrations of the technical architecture.
-
And finally, regression test cases are needed as an instrument to be able to make changes to the application safely. All changes go through a set of regression test cases before they are integrated into the application, which covers all the essential functions of the system. Each regression test case must refer to one or more requirements, the fulfillment of which it checks. This ensures that a change that passes all regression test cases does not damage the functionality of the application.
When it comes to temporary documentation, it should meet the requirements of development and be designed for easy integration into the permanent documentation. The following are essential:
-
a description of the new and changed requirements in the same form and nomenclature (e.g. numbering) as in the permanent documentation;
-
Changes to the technical entity diagram: It can be used from the permanent documentation and only the changes are entered and highlighted;
-
Context diagram changes;
-
Changes in technical architecture;
-
If necessary, other temporary documents that are required for development so that they can be carried out offshore (database models, class diagrams, etc.);
-
Test cases (including regression test cases) that refer to requirements.
After the development project has been completed, the permanent documentation can easily be adapted from the temporary documents. The documents are then updated there and made available in a new version.
The question still arises of a more modern HOW. Documentation can continue to be in the form of Word and other documents. Version security can thus be created at least manually. However, searchability and linkability are still not available, which makes the use of the documentation significantly more difficult.
It is therefore advisable to use the possibilities of tools such as JIRA or Confluence for the documentation. Texts and diagrams are searchable, individual elements can be linked, such as test cases or requirements. For example, if you are looking for the effects of an erro
r in operation, it will be easier to find the associated requirement and can thus better estimate the effects of the error. In order to ensure version security here, however, it is still necessary to save the current version of the documentation after the change has been made.
It is certainly not worthwhile to rework extensive existing documentation for large systems in this way. But if you start with economical documentation for new systems in this sense, you will save a lot of effort now and in the future. (hv)