Software documentation

With software documentation refers to the documentation of computer software. She explains to users and users in different roles, how the software works, what they produced and processed (eg, data ), as it is to use what is necessary for its operation and the bases on which it was developed.

Species

The full documentation for a software product is composed of different parts, which are aimed at different target groups:

Some parts remain confidential documentation in the field of developer, others have to be available for the users. Sometimes they meet in addition to technical and legal purposes, as part of the contract and in case of warranty claims.

In summary, the software documentation are distinguished by:

If this distinction is already taken into account during the project, so the effort for creating system documents (which are necessary for the introduction ) can be largely reduced.

Legal overview

The law considers software from a completely different angle than the computer science, namely, for example under the aspects of consumer protection, liability and warranty etc. Software products here are merely a variant of ' products ', among many other species. From this perspective, one of software products and documentation.

To this end, a quote by Beckmann: " According to the jurisprudence of the BGH on the topic, computer user documentation ' is to be regarded as settled that, regardless of the eligible contract type, the software license obligation in addition to the transfer of the program and for transfer of the relevant program information. It should be noted that it is not only contrary is a standing mutual obligations principal obligation of the supplier about a side - but, both in standard as well as custom software. "

The legal language is different from the rest of the applying in the industry: Documents as above all the instructions for use here include the "instructions". "Documentation" in the strict legal sense, however, includes only logs and records about the career of a product, ie the development, production, testing, delivery ( sweg ); Source: When reference is made in the preceding paragraph of " computer user documentation ", it's obviously a court decision that adapts for a specific case in the choice of words of information technology.

Historical development and modern forms

The nature and scope of software documentation have changed significantly since the 1960s and 1970s to the present.

In Germany it was from the 1980s three standards in the field "information processing", which were withdrawn in June 2004 without replacement, because they could not be implemented timely:

• DIN 66230 Program Documentation
• DIN 66231 program development documentation
• DIN 66232 data documentation

Although there standardized paper form became obsolete, the goals and basic principles are still relevant today.

Programmer documentation

The first applications were punched into cards and had a relatively low level, or about several thousand rows. Comments in the source code were rare. Spaces they avoided where syntactically allowed, so the whole statement could fit in the 72-80 columns of a map and not a consequence of card would lug around. Only uppercase letters were possible; the length of the names of variables and functions was severely limited (often only 6 characters). The source code was thus difficult to read. The programmers documentation then had to explain in a separate document in detail and with flowcharts, line by line the function.

This is not possible today. The scope of current software systems and the speed changes can be made with a variety of programmers, let the long standing practice not to. But allow modern programming languages ​​and unlimited amount of text along with interactive displays, a different procedure.

Modern software documentation pursuing other approaches:

• The source code should be self-explanatory. The names of variables and functions to be intuitively understandable for humans. Where itself already sufficiently explained the formal programming language and the structure by appropriately engaging and disengaging of control structures is sufficiently clear, no additional and independent description must be made - with changes in the program, it immediately comes to misclosures and inconsistencies. The human resources for the timely maintenance of superfluous documents are regularly absent.
• The documentation should be as far as possible incorporated into the source code. This can be achieved by commenting and comment lines that are in close proximity to the instructions in the source code and can be updated immediately when they change. During further processing by other programmers who can work distributed worldwide, there is always the current annotation is available and can be adjusted. What has already been explained by the formal programming language itself, must not be content an additional comment.
• Supporting statements should be generated with documentation tools automatically from the source code and specially formatted comments. Utilities such as Javadoc or Doxygen can create complex hypertext reference, with which the developers can quickly find also in large systems. Integrated development environments provide interactively and graphical overviews such as structural trees. The data structure of objects can be illustrated in the form of static graphics ( on paper) and dynamic ( with interactive navigation ).
• As far as notes, sketches and the like can not be integrated in the source code itself, it should be stored as files directly from the appropriate files of the source code and distributed together so that they are all available to developers and it does not lead to inconsistencies.

The programmers documentation in the narrower sense is aimed at programming the source code itself. In addition to this "internal" documentation, there is often an "outward " oriented documentation, which turns to other programmers that use a programming interface.

Sensible programmers documentation is now virtually created only in electronic form and not more than paper documents and books:

• The frequent and varied changes can be immediately printed works obsolete.
• Electronic documents can be made available worldwide in the current form available.
• The products are so complex that a table of contents or an alphabetical index is not sufficient to navigate through the system. Required are interactive electronic tools such as hyperlinks, search and dynamically showing and hiding changing views on the amount of information.

User documentation

The user documentation serves the user to explain the application of the program.

For user documentation are now additionally:

• Context-sensitive help at any point in the program flow.
• Online version of a printed User's Manual on the local hard disk, with hyperlinks and direct reference to individual sites from the help function out.
• Updated information on the website of the developer.
• Guided tour of the user interface as the first entry.
• Agents and assistants who help as rule-based system targeted questions to the user in solving complex problems.

In an understandable for the expected user language is to pay particular attention.

Traditionally it has been delivered to the software simply a manual. This has changed with graphical user interfaces. You should already be self-explanatory and intuitive to suggest the correct operation.

A good user manual consists of:

• Information on the function of the software in the view of the problem world of the user.
• A basic manual.
• Advice for troubleshooting, fault analysis countermeasures.
• A tutorial in which the solution of some of the exercises is exemplary possible and are accompanied standalone solution attempts ideally and dissolved at failure.
• Frequently Asked Questions ( FAQ ) in clear outline.
• Glossary Definitions of terms used.