In contrast to mechanical engineering or the manufacturing of medical products, within Germany no legal foundation exists within the IT sector that mandates a company to furnish User Documentation. Although the German Civil Code (BGB) does require an installation manual, other forms of User Documentation are left to contract drafting. Consequently, the costs of User Documentation could easily be saved, right?
Let's answer this provocative question right away: no. This is because User Documentation has many benefits.
What is User Documentation?
Software Documentation can be divided into two types: System Documentation and User Documentation. System Documentation, on the one hand, assists in the development of software. It describes the requirements for the software and its technical functioning. Documents on quality assurance are also part of System Documentation.
User Documentation, on the other hand, is specifically aimed at the users of the software. It includes information on features, business processes, and use, but also on installation, interfaces, and adaptation of the software.
Quality Criteria
Quality User Documentation contains information on all tasks that occur in the course of a product’s life cycle. The information is correct with regard to the corresponding field and refers to the current release status of the product. Incidental information is omitted for the sake of readability, and illustrations are only used if they offer added value for the transmission of information.
The contents of the User Documentation are consistent and build upon each other logically. Readers usually expect a document to have a certain structure. In a user manual, for example, fundamental operational concepts are likely explained prior to more infrequent business transactions, and details about tariff modeling wouldn't typically be anticipated within the chapter concerning pension disbursements .
What is considered understandable and logical depends on the target group of a document. Depending on their own area of responsibility and background knowledge, readers require different types of information. This in turn has an impact on the level of technicality and abstraction of the content. For example, one target group may need fewer details, while another may require additional explanations.
Consistency is demonstrated further through the utilization of concise language and uniform technical terminology, which helps prevent any potential misunderstandings. Redundancies and filler words can be omitted; sentences should be short and contain clear grammatical references. A verbal style of writing should be sought after. After all, there are few things worse than sentences whose beginning you can no longer remember. In this respect, the controlled language of technical documentation is clearly different from the largely redundant everyday language.
A clear document layout further emphasizes the structure of the content. The layout should follow a pleasant color scheme. Structural elements such as list points, ticks, arrows, and the like, visually support the technical content and guide the reader through the document.
Further comprehensive guidelines for qualitative user documentation are described in ISO 82079-1 and the standard series ISO/IEC 2651x.
Processes are Essential
Quality User Documentation is the result of a complex, strategic information development process. The German Society for Technical Communication - tekom Deutschland e. V., describes technical communication as a "process of defining, creating and providing information products for the safe, efficient and effective use of products (technical systems, software, service)." User Documentation thus go through a life cycle to which various stakeholders are involved in its many different phases.
This life cycle requires qualified staff who know and can implement the necessary methods, and appropriate tooling to consistently manage User Documentation. It is the only way to ensure that the documentation meets the quality criteria described.
Advantages of User Documentation
But why bother at all? Well, User Documentation makes it possible to collect relevant information in one central place. Information is more easily accessible, which in turn facilitates knowledge sharing.
All stakeholders benefit from the resulting transparency throughout the entire life cycle of the software. For customers, the functional scope of the software is always clear thanks to the Product Description. There is no danger of buying a software blindly. And for the software company, too, the User Documentation serves as a safeguard for the product offered. For this reason, the documentation is usually part of the contract documents.
On the basis of the Processes Manual, the requirements of the individual customer can be determined in the delta analysis before the project begins. During the project, the Setup and Installation Manual, the Architecture Manual, the Mathematics Manual, and the Interfaces Manual support the implementation of the software in the customer's system landscape. The Adaptation Manual accompanies the implementation of any necessary adaptations. New employees can be trained more quickly and integrated into an existing team.
Finally, in the daily use of the software, the User Manual ensures the software is used as intended by the agents.
User Documentation is therefore a significant reference tool for dealing with software and ensures its future viability. For this reason, User Documentation is to be understood as part of the finished product: faulty or incomplete information on the use of a software thus leads to a faulty product overall.
The Key Points in a Nutshell
User Documentation provides users with all the necessary information about a software throughout its life cycle. To accomplish this , documentation must meet certain quality criteria: completeness, minimalism, correctness, conciseness, consistency, comprehensibility and accessibility. The extent to which these quality criteria are met varies depending on the intended use and the target group of the documentation. User Documentation is complex, which is why it is essential to have clear processes, qualified staff, and dedicated tools for its support. A Department of Technical Communication is therefore more than worthwhile for a software company.
Do you have any questions or comments? Then please leave us a comment.