Software documentation

With software documentation refers to the documentation of software . It explains to developers , users (client, customer) and end users in different roles how the software works, what it generates and processes (e.g. data ), how it is to be used, what is required for its operation and on which Basics it was developed.

species

The documentation for a software product consists of different parts that are aimed at different target groups:

Method documentation: General description of the fundamentals on which the software is based. These can be mathematical algorithms , technical-scientific or commercial processes, which can be referred to in the other parts of the documentation. The software implements these methods; However, the method documentation makes no reference to technical details of the programming, which can change frequently. The method documentation is written from the world of users.
Programmer documentation: Description of the source code .
Installation documentation: Description of the required hardware and software, possible operating systems and versions, required software environment such as standard libraries and runtime systems . Explanation of the procedures for installation, also for maintenance (updates) and de-installation, for small products a readme file.
The target group are administrators at users who do not necessarily have to use the software directly themselves.
User documentation: Information material for the actual end-user , such as through the user interface . The method documentation can also be made available to users in order to provide background information and a general understanding of the functions of the software.
Data documentation: More detailed descriptions of the data are often required. The interpretation of the information in the real world, formats, data types , restrictions (value range, size) must be named. The data documentation can often be divided into two areas: inner data structures , as they are only visible to programmers and outer data documentation for those data elements that are visible to users - information to be entered by end users and output by the software. This also includes a detailed description of possible import / export interfaces .
Test documentation: Evidence of test cases that can be used to test the proper functioning of each version of the product, as well as procedures and scenarios that have successfully verified correctness in the past.
Development documentation: Evidence of the individual versions based on changes (e.g. in patch or release notes), the respective underlying goals and requirements and the concepts used as specifications (e.g. in specifications and functional specifications ); involved persons and organizational units; successful and unsuccessful development directions; Planning and decision documents etc.

Some parts of the documentation remain confidential in the area of the developer, others must be available to the users. In addition to technical purposes, they sometimes also serve legal purposes, as part of a contract and in the event of warranty claims.

In summary, the software documentation can be divided into:

Project documents: They describe what should (or was) done by those involved in development - why (e.g. goals, requirements), how (methodology), when (planning documents), with what (tools) etc.
System documents: They describe the system - what it consists of, what it does (functions), what it generates (results), what data it processes, how it is to be operated, etc.

If this distinction is already taken into account in the course of the project, the effort for creating system documents (which are required for implementation) can be largely reduced.

Legal point of view

The law considers software from a completely different angle than the computer science , namely z. B. under the aspects of consumer protection , liability and warranty, etc. Software products are only one variant of 'products' among many other types. From this point of view, software products also include documentation.

Here is a quote from Beckmann: "According to the case law of the Federal Court of Justice on the subject of 'EDP user documentation', it is to be regarded as clarified that, regardless of the type of contract in question, the provision of software requires not only the provision of the program but also the provision of the corresponding program information. It should be noted that this is not only a secondary, but rather a reciprocal main obligation of the supplier, both for standard and individual software. "

The legal linguistic usage differs from that in the applying industry: documents like above all the instructions for use belong to the "instructions". “Documentation” in the narrower legal sense, on the other hand, only includes protocols and documents relating to the development of a product, i.e. about development, production, testing, delivery (sweg); Source: If “IT user documentation” is mentioned in the previous paragraph, it is obviously a matter of a court decision that adapts to the choice of words used in information technology for a specific case.

Historical development and modern forms

The type and scope of software documentation has changed significantly since the 1960s and 1970s until today.

In Germany there were three standards in the field of "information processing" from the 1980s, which were withdrawn without replacement in June 2004 because they could no longer be implemented in a contemporary manner:

DIN 66230 program documentation
DIN 66231 program development documentation
DIN 66232 data documentation

Even though the paper form standardized there has become obsolete, the goals and basic principles are still relevant.

Programmer documentation

The first application programs were punched on punched cards and were relatively small in size, around a few thousand lines. Comments in the source code were rare. Spaces were avoided where syntactically permissible, so that the entire statement would fit into the 72–80 columns of a card and no subsequent card would have to be carried along. Only capital letters were possible; the length of the names of variables and functions was very limited (often only 6 characters). This made the source code difficult to read. The programmer documentation then had to explain the function in a separate document in detail and with flow charts line by line.

This is no longer possible today. The scope of current software systems and the speed with which changes can be made by a large number of programmers no longer allow the traditional approach. Modern programming languages and unlimited text volume together with interactive representations allow a different approach.

Modern software documentation takes different approaches:

The source code should be self-explanatory .
The names of variables and functions should be intuitively understandable for people. Where the formal programming language itself is sufficiently explained and the structure is already sufficiently clear through the appropriate indentation and disengagement of control structures , no additional and independent description may have to be prepared; otherwise inconsistencies will occur immediately if the program is changed. The human resources for the timely maintenance of superfluous documents are regularly not available.
The documentation should be incorporated into the source code as far as possible.
This can be achieved through comments and comment lines that are in the immediate vicinity of the instructions in the source code and can be updated immediately if they are changed. For further processing by other programmers who can work around the world, the current comment is always available and can be further adapted. What has already been explained by the formal programming language itself must not be the content of an additional comment.
Supporting overviews should be generated automatically from the source code and specially formatted comments using documentation tools.
Utility programs such as Javadoc or Doxygen can create complex hypertexts as reference, with which the developers can quickly find their way around even in large systems. Integrated development environments also interactively compile graphical overviews such as structure trees. The data structure of objects can be illustrated statically (on paper) and dynamically (through interactive navigation) in the form of graphics.
If comments, sketches and the like cannot be integrated into the source code itself, they should be saved as files directly with the corresponding files in the source code and distributed together so that they are available to all developers and there are no inconsistencies.

The programmer documentation in the narrower sense aims at the programming of the source code itself. In addition to this "internal" documentation, there is often also an "external" documentation, which is aimed at other programmers who use a programming interface .

Nowadays, meaningful programmer documentation is practically only created in electronic form and no longer as paper documents and books:

The frequent and varied changes make printed works immediately obsolete.
Electronic documents can be made immediately available worldwide in their current form.
The products become so complex that a table of contents or an alphabetical register is insufficient to navigate the system. Interactive electronic aids such as hyperlinks , search functions and dynamically changing views of the amount of information by fading in and out are required .
In a change log ( english changelog ) are abbreviated form documenting changes, but not the details. In doing so, reference is made primarily to differences to previous versions of software, which is intended to provide an overview.

User documentation

The user documentation is used to explain the application of the program to the user.

The user documentation now also includes:

Context-sensitive help at every point in the program flow.
Online version of a printed user manual on the local hard drive, with hyperlinks and direct reference to individual references from the help function .
Updated information on the developers website.
Guided tour through the user guidance as a first introduction.
Agents and assistants which, as a rule-based system, help the user to solve complex problems by asking specific questions.

Particular attention must be paid to language that is understandable for the expected user.

Traditionally, a manual for the software was simply delivered. That has changed with graphical user interfaces . They should already be self-explanatory and intuitively suggest the correct operation.

A good user manual consists of:

Information on the functionality of the software, its input data and the results generated - from the perspective of the user .
A basic instruction manual .
Advice on troubleshooting, error analysis with countermeasures.
A tutorial in which the solution of some exercises is possible and ideally accompanied by independent attempted solutions and resolved in the event of failure.
Frequently Asked Questions (FAQ) in a clear structure.
Glossary with an explanation of the technical terms .

literature

Franz Lehner: Software documentation and measurement of the documentation quality . Hanser, 1994, ISBN 3-446-17657-8 (final stage of paper-based formats; basics and content-related requirements timeless).

Individual evidence

↑ Beckmann. In: CR , 9/98, p. 519 ff.
↑ Legal seminar for manual authors on the occasion of the introduction of the Product Liability Act

[1] Beckmann. In: CR , 9/98, p. 519 ff.

[2] Legal seminar for manual authors on the occasion of the introduction of the Product Liability Act