Business-Blog | adesso insurance solutions

Technische Redaktion: Anwendungs­dokumen­tation mit Qualität

Geschrieben von Heike Schroers | 24.08.2023

Für die IT-Branche gibt es in Deutschland im Gegensatz zum Maschinenbau oder der Herstellung von Medizinprodukten keine gesetzliche Grundlage, die ein Unternehmen zur Bereitstellung einer Anwendungsdokumentation verpflichtet. Das BGB fordert zwar eine Installationsanleitung; weitere Formen der Anwendungsdokumentation bleiben allerdings der Vertragsgestaltung überlassen. Demnach könnte man sich die Aufwände für Anwendungsdokumentation eigentlich auch sparen, oder nicht?

Die Antwort auf diese provokante Frage gleich vorweg: Nein, denn Anwendungsdokumentation lohnt sich.

Was ist Anwendungsdokumentation?

Die Softwaredokumentation unterscheidet zwischen Entwicklungsdokumentation und Anwendungsdokumentation: Entwicklungsdokumentation dient der Entwicklung einer Software. In ihr sind Anforderungen an die Software und deren technische Funktionsweise beschrieben. Auch Dokumente zur Qualitätssicherung gehören zur Entwicklungsdokumentation.

Anwendungsdokumentation hingegen richtet sich an die Nutzer:innen der Software. Sie umfasst Informationen zu Funktionen, Geschäftsvorgängen und Bedienung; aber auch zu Installation, Schnittstellen und Anpassung der Software.

Qualitätskriterien

Qualitative Anwendungsdokumentation enthält Informationen zu sämtlichen Aufgaben, die im Laufe des Produktlebenszyklus anfallen. Die Informationen sind fachlich korrekt und beziehen sich auf den aktuellen Release-Stand. Auf nebensächliche Informationen wird der Lesbarkeit halber verzichtet und auch Abbildungen werden nur verwendet, wenn sie einen Mehrwert für die Informationsübermittlung bieten.

Die Inhalte der Anwendungsdokumentation sind konsistent und bauen logisch aufeinander auf. Leser:innen haben in der Regel eine Erwartungshaltung an den Aufbau eines Dokuments: In einem Benutzungshandbuch werden z. B. grundlegende Bedienkonzepte vermutlich vor selteneren Geschäftsvorgängen beschrieben und Informationen zur Tarifmodellierung würde man wohl kaum im Kapitel zur Rentenauszahlung erwarten.

Was als verständlich und logisch angesehen wird, hängt dabei von der Zielgruppe eines Dokuments ab. Je nach eigenem Aufgabenbereich und Hintergrundwissen bedürfen Leser:innen unterschiedlicher Informationen. Dies wiederum hat Auswirkungen auf Fachlichkeitsgrad und Abstraktionsniveau der Inhalte. So reichen der einen Zielgruppe vielleicht weniger Details, während die andere zusätzliche Erklärungen zu einem Sachverhalt benötigt.

Konsistenz zeigt sich auch in der Verwendung prägnanter Formulierungen und gleichbleibender Fachbegriffe, die verhindern, dass Missverständnisse entstehen. Redundanzen und Füllwörter können weggelassen werden; Sätze sollten kurz sein und eindeutige grammatische Bezüge enthalten. Der Verbalstil ist zu bevorzugen. Schliesslich gibt es kaum Schlimmeres als Sätze, von denen man am Ende nicht mehr weiss, wie sie angefangen haben. Insofern unterscheidet sich die kontrollierte Sprache technischer Dokumentation deutlich von der weitestgehend redundanten Alltagssprache.

Ein übersichtliches Layout hebt die inhaltliche Struktur weiter hervor. Das Layout sollte einer angenehmen Farbgebung folgen. Strukturelemente wie Listenpunkte, Häkchen, Pfeile etc. unterstützen die fachlichen Inhalte visuell und leiten die Leser:innen durch das Dokument.

Weitere umfangreiche Richtlinien für qualitative Anwendungsdokumentation sind in der ISO 82079-1 und der Normenreihe ISO/IEC 2651x beschrieben.

Ohne Prozesse geht es nicht

Qualitative Anwenderdokumentation ist das Ergebnis eines komplexen, strategischen Informationsentwicklungsprozesses. Die Gesellschaft für Technische Kommunikation – tekom Deutschland e. V. beschreibt technische Kommunikation als „Prozess der Definition, Erstellung und Bereitstellung von Informationsprodukten für die sichere, effiziente und effektive Verwendung von Produkten (technische Systeme, Software, Dienstleistung)“. Anwendungsdokumentation durchläuft also einen Lebenszyklus, an dessen Phasen verschiedene Stakeholder beteiligt sind.

Es braucht qualifizierte Mitarbeiter:innen, welche die nötigen Methoden kennen und diese umsetzen können sowie ein angemessenes Tooling, um Anwendungsdokumentation konsequent zu betreuen. Nur so kann sichergestellt werden, dass die Dokumentation den beschriebenen Qualitätskriterien entspricht.

Vorteile von Anwendungsdokumentation

Aber warum das Ganze? Anwendungsdokumentation ermöglicht es, relevante Informationen an einer zentralen Stelle zu sammeln. Die Informationen sind leichter zugänglich, was wiederum den Wissensaustausch vereinfacht.

Von der so entstandenen Transparenz profitieren alle Stakeholder über den gesamten Lebenszyklus der Software hinweg: Für Kund:innen ist der Funktionsumfang einer Software dank der Leistungsbeschreibung stets nachvollziehbar. Die Gefahr, etwa die Katze im Sack zu kaufen, besteht dabei nicht. Aber auch für das Softwareunternehmen dient die Anwendungsdokumentation als Absicherung über die angebotene Leistung. Aus diesem Grund ist die Dokumentation zumeist Teil der Vertragsunterlagen.

Auf Basis des Handbuchs Prozesse können vor Projektbeginn in der Delta-Analyse die individuellen Kund:innen-Anforderungen ermittelt werden. Im Projekt unterstützen das Handbuch Einrichtung und Installation, das Handbuch Architektur, das Handbuch Mathematik und das Handbuch Schnittstellen die Implementierung der Software in die Systemlandschaft der Kund:innen. Das Handbuch Anpassung begleitet die Umsetzung ggf. notwendiger Anpassungen. Neue Mitarbeiter:innen lassen sich zudem schneller einarbeiten und in ein bestehendes Team integrieren.

In der täglichen Arbeit mit der Software schliesslich, gewährleistet das Benutzerhandbuch die sachgemässe Nutzung der Software durch die Sachbearbeitung.

Anwendungsdokumentation ist also ein bedeutsames Referenzwerkzeug für den Umgang mit Software und sorgt für deren Zukunftsfähigkeit. Aus diesem Grund ist Anwendungsdokumentation als Teil des fertigen Produkts zu verstehen: Fehlerhafte oder unvollständige Informationen zur Anwendung einer Software führen somit zu einem fehlerhaften Gesamtprodukt.

Das Wichtigste in Kürze

Anwendungsdokumentation bietet Nutzer:innen alle notwendigen Informationen zu einer Software über den gesamten Lebenszyklus der Software hinweg. Um diese Aufgabe zu erfüllen, muss die Dokumentation gewissen Qualitätskriterien entsprechen: Vollständigkeit, Minimalismus, Korrektheit, Prägnanz, Konsistenz, Verständlichkeit und Zugänglichkeit. Die Ausprägung dieser Qualitätskriterien variiert je nach Verwendungszweck und Zielgruppe der Dokumentation. Anwendungsdokumentation ist komplex, weswegen eingängige Prozesse, qualifizierte Mitarbeiter:innen und dedizierte Tools für ihre Betreuung unabdingbar sind. Eine technische Redaktion ist also für ein Softwareunternehmen mehr als lohnenswert.

Sie möchten mehr über unsere Software erfahren? Wenden Sie sich gerne an unseren Experten Karsten Schmitt, Head of Business Development.