The term documentation is to be seen as a kind of collective term for many different documents in the field of software. What they all have in common is that they offer a reference point for different target groups on the structure, function, use or development of the software under consideration. However, the same terms are not always used for the different types of documentation.
Process documentation vs. product documentation
The main difference between different types of documentation is whether it is process documentation or product documentation. Process documentation describes the course of the software project, from creation to the end of software maintenance. It serves as an authoritative guide in the development of the system and ensures that internal knowledge is retained. The goal of process documentation is to structure and organize software development. At the same time, it helps to make the project more transparent and reduces the administrative effort. Typical documents that are included in process documentation are forecasts, schedules, and organizational and process standards. Many process documents are quickly outdated because they are only required for a specific phase of the development process. Nonetheless, they can be useful in implementing similar tasks or in future maintenance.
The product documentation describes the software product to be developed. A distinction is also made between two sub-types of product documentation; the user documentation and the system documentation.
The user documentation
User documentation describes how the software is to be installed, operated and maintained for different user groups. The best-known type of user documentation is end-user documentation, often also called user manual. The target group of the software to be created largely decides the content and scope of the documentation. In the case of large software projects, it can be very helpful to outsource the documentation to specialized companies or an internal department. This can avoid legal problems. In general, however, the focus should be on descriptive examples rather than on technical subtleties. Another form of user documentation that often does not receive as much attention as end-user documentation is administrator documentation. Typically, this documentation includes all information that is necessary for installing and maintaining the software. The documentation explains different behavior of the system in different environments and when interacting with different other systems. It also provides information about the necessary requirements and any error messages.
The system documentation
The system documentation includes all documents that describe the software system. The following elements are often part of such documentation:
- Requirements documentation,
- Architecture documentation,
- Source code documentation,
- Quality assurance documentation,
- Interface documentation
Information on the functionality of the software is summarized under the requirements documentation area. These include user stories and use cases. To keep the document clear, it should only contain the essential information about the purpose of the software, its properties, its functionalities and its behavior. In the documentation of the architecture, the most important decisions on the structure and design of the software are recorded and planned components and their significance are listed. Another technical section is the documentation of the source code. The document explains to developers how the code works. The document on quality assurance documentation not only contains test cases that ensure the required function of the software, but also procedures that are used. In the interface documentation, all the interfaces available in the system and used by the system are summarized. The documentation provides an overview of the software’s options.
When developing software, every area of the development process must be adequately documented. Both no documentation and excessive documentation damage the course of the project. Depending on the system, the focus is on different areas of the documentation. The documentation should be kept up to date at all times and reflect the current state of development.
Sysparency offers the possibility to create documentation automatically and in compliance with the law, thereby relieving your team of software development. Either technical, functional and structural documentation are possible. It does not matter whether it is a current development or the subsequent documentation of already existing software.