Softwaredokumentation: Grundlagen für gute Softwareanleitungen

Durchblick im Software-Dschungel
Fundamentale Informationen für gute Software- und IT-Service Anleitungen

Die Spannweite der Qualität von Softwareanleitungen ist groß. Bedienungsanleitungen, die „pauschal“ für alle Zielgruppen gleich erstellt werden sind weder nutzungsfreundlich noch hilfreich. Leider allerdings auch nicht selten.

Steche mit deinen Anleitungen aus der Menge heraus, lerne in diesem Artikel die Basics für gute Softwareanleitungen und erfahre, welche Normen und Richtlinien für Software-Dokumentationen relevant sind.

Eine gute Technische Kommunikation unterstützt die Benutzer:innen dabei ihre Aufgaben mit dem Produkt effektiv zu erledigen. Sie trägt maßgeblich zur Effizienz bei der Erledigung der Aufgaben bei,  ist leicht zu finden, einfach zu lesen und vor allem hilfreich! Eine fundierte Analyse des IST-Zustands und des Bedarfs an Informationsprodukten für deine Nutzer:innen bilden das Fundament für maßgeschneiderte User-Assistance.

Es ist unabdingbar, zunächst klar zwischen interner und externer Softwaredokumentation zu unterscheiden, um die Arten von und den Bedarf an Dokumentation klar zu definieren.

Was gehört zur internen Softwaredokumentation?

Mit der internen Softwaredokumentation ist diejenige Dokumentation gemeint, mit der du deine internen Aufgaben, Entwicklungsschritte und Prozessabläufe dokumentierst. Damit soll bestmöglich sichergestellt werden, dass sämtliche Projekt-Entscheidungen auch zu einem späteren Zeitpunkt von allen Beteiligten nachvollzogen werden und der Wissensverlust durch Personalwechsel auf ein Minimum reduziert wird.

Beispiele für interne Softwarebeschreibungen

• Projektdokumentation (Pflichtenheft, User-Stories, Backlogs, Use-Cases)
• Systemdokumentation (Code-Kommentare, Software- und UI-Design, Architekturdokumentation)
• Schnittstellendokumentation (API, GUI, Bussysteme etc.)
• Testdokumentation, Software-Spezifikationen etc.
• Prozessdokumentation, Definition of Done etc.

Warum du interne Software-Beschreibungen erstellen solltest

Warum geben wir uns in Zeiten schnell aufeinander folgender Produkt-/Software-Releases überhaupt die Mühe, die internen Softwareentwicklungszustände permanent zu dokumentieren? Du fragst dich ohnehin schon, WANN du das alles dokumentieren und vor allem WIE du es aktuell halten sollst.

„Wir dokumentieren für das Unternehmen, um Wissen zu transferieren und zu speichern. Für jetzt und für die Zukunft“

Gründe für eine interne Dokumentation deiner Produkte

Dokumentiere,

• um Wissen für eine erneute Weiterentwicklung der Software zu konservieren,
• zu Qualitätssicherungszwecken und um den Normen gerecht zu werden, die es zur
  Softwaredokumentation gibt,
• um Prozesse und Abläufe zu optimieren,
• um Personalausfälle abzufangen,
• um dadurch langfristig Geld zu sparen und das Rad für die Softwareentwicklung nicht jedes Mal neu erfinden zu müssen.

Äußere Einflussfaktoren, die eine firmeninterne Softwaredokumentation unabdinglich machen

Jede Software, die für ein Produkt größeren Umfangs entwickelt wird, erfordert mehrere Entscheidungen. In der meist langen Designphase mit wechselnen Mitarbeiter:innen und grundsätzlich vielen involvierten Personen stellen sich schon beim bloßen Skizzieren des grafischen Designs, der Benutzungsinteraktion, der Komplexität und des Funktionsumfangs der Software zahlreiche Fragen, die nicht ohne eindeutige Entscheidung auskommen, auch wenn es verschiedene Lösungsansätze gibt.

Jede dieser getroffenen Entscheidungen führt letztlich dazu, dass der Quellcode fortgeschrieben und die Software entwickelt wird.

Diese im Projekt aufkommenden Fragen, Schwierigkeiten sowie die getroffenen Entscheidungen NICHT zu dokumentieren, führt meist schon nach kurzer Zeit dazu, dass nicht mehr nachvollzogen werden kann, warum ein bestimmter Weg eingeschlagen wurde und nicht doch ein anderer.

Fragen, die nach kurzer Zeit ohne Dokumentation bereits nicht mehr qualitativ hochwertig beantwortet werden können:

• Welche Fragestellung hat überhaupt eine Entscheidung gefordert?
• Welches waren die ausschlaggebenden Gründe für die getroffene Entscheidung?
• Welche alternativen Lösungsmöglichkeiten gab es außerdem und warum wurden diese außer Acht gelassen?

Was ist externe Softwaredokumentation?

Mit der externen Softwaredokumentation ist diejenige Dokumentation gemeint, mit der die Software als Produkt oder als Bestandteil eines Produkts für den Endnutzer dokumentiert wird. Die Funktionsweise sowie Handlungsbeschreibungen werden vermittelt, sodass die Endnutzer:innen mit der Software gut umgehen können und sie verstehen. Die Dokumentation von Software für extern ist stark zielgruppengebunden.

Beispiele: Gebrauchsanleitung, Installationsanleitung, Online-Hilfen, Schulungsunterlagen etc.

Welche Anforderungen gibt es an Software-Informationsprodukte?

Achte darauf, dass die mit dem Software-Produkt ausgelieferten Informationsprodukte folgende Anforderungen erfüllen:

• Vollständig, sachlich korrekt und aktuell.
• Befähigen zur intuitiven Anwendung des Produkts.
• Unterstützen die Anwender:innen zielführend bei der Lösung seiner Aufgabe.
• Navigieren die Benutzer:innen mittels durchdachter Navigationskonzepte zum für sie relevanten Topic.
• Bieten eine umfassende Suchfunktion.
• Verwenden eine konsistente und den Benutzer:innen angepasste Sprache. Fachausdrücke, die sich nicht vermeiden lassen, werden erklärt.
• Berücksichtigen relevante Normen und die Grundanforderungen an die Technische Kommunikation.
• Sollten nicht nur als PDF-Datei vorliegen sondern kontextsensitiv bereitgestellt werden.
• Stellen im besten Fall eine Feedbackfunktion und Auswertungsmechanismen bereit.

Warum solltest du deine Produkte dokumentieren?

Auch im Bereich der Software gilt: Die Dokumentation ist immer Bestandteil des Produkts (ISO IEC IEEE 26514).

Zwar gibt es keine gesetzliche Vorschrift für die Anwender:innen von Software eine besondere Dokumentation in bestimmter Form bereitzustellen. Jedoch sind die Produkthersteller:innen immer für ihr gesamtes Produkt verantwortlich:

• Die Hersteller:innen von Software als eigenständiges Produkt sind verantwortlich im Sinne des Vertragsrechst (von diesen Software-Produkten geht in der Regel nur ein sehr geringes bis kein Sicherheitsrisiko aus, Bsp.: Bildbearbeitungs-Software).
• Die Hersteller:innen von Software als Bestandteil eines Produkts sind verantwortlich im Sinne des Produktsicherheitsrechts und des Produkthaftungsrechts (denn von diesen Software-Produkten können sehr hohe Sicherheitsrisiken ausgehen, Bsp.: Software einer Produktionsanlage).

Außerdem leisten die Hersteller:innen mit dem Verkauf und der Auslieferung von Software eine Gewähr für ihr Produkt, die in vielen Fällen auch über die gesetzliche Gewährleistungsfrist hinausgeht.

Doch was noch viel wichtiger ist und was Unternehmen und Firmen hauptsächlich dazu antreibt, eine saubere und vielleicht sogar schon intelligente Dokumentation mit dem Produkt auszuliefern, sind folgende Vorteile:

Dokumentation im agilen Entwicklungsumfeld

Eine umfassende Beschreibung und Erklärung sowie den Ursprung des heute so gängigen Begriffs „agil“ und der dazugehörigen „agilen Softwareentwicklung“ findest du überall im Netz. Weil zur Softwarenentwicklung immer auch die passende Softwaredokumentation gehört, spricht man häufig allerdings auch direkt von „agiler Softwaredokumentation“. Damit ist selbstverständlich nicht gemeint, dass die einzelnen Informationsprodukte agil sind, sondern vielmehr ihr Entstehungsprozess: der agile Prozess der Dokumentation. An dieser Stelle wollen wir deshalb nur einen kleinen Einblick liefern.

Viele Unternehmen stehen vor der Herausforderung, nicht zu wissen, wie sie in Zeiten schnell aufeinander folgender Produkt-Releases mit der Dokumentation hinterher kommen sollen. Festzuhalten ist an dieser Stelle, dass eine agile Vorgehensweise nicht für jedes Unternehmen und jedes Softwareprodukt geeignet oder gar erforderlich ist. Agile Entwicklungsprozesse setzen sehr gute Teamzusammenarbeit/-kommunikation, selbstsichere Persönlichkeiten und ein Umdenken in den Köpfen der Mitarbeiter:innen voraus.

Wie du agil dokumentieren kannst

Bei der agilen Dokumentation wird, bedingt durch die Faktoren Zeit und Aktualität, deutlich weniger Dokumentation erzeugt als bei traditionellen Dokumentationsprozessen. Dennoch erwarten die Endnutzer:innen der Software eine qualitativ gleichwertige Benutzerdokumentation, die sie bestmöglich in der Anwendung unterstützt.

Hier gilt es, den Unterschied in der technischen Kommunikation durch andere Kommunikationswege auszugleichen. Der Fokus liegt auf der aktiven Kommunikation mit den Kund:innen/Endbenutzer:innen der Software. Durch regelmäßiges Feedback von Kund:innen zur Software und zur Dokumentation wird die Qualität gesichert und das Ergebnis geliefert, das den Anforderungen der Anwender:innen entspricht. Demzufolge finden im agilen Kontext nach Scrum, Kanban oder ähnlichen Methoden, Teil-Produktauslieferungen bereits nach sehr kurzen, oft als Sprints oder Iterationen bezeichneten Intervallen statt (ab 1-2 Wochen aufwärts). Pro Sprint wird versucht, eine Software-Funktionalität vollständig umzusetzen und auszuliefern.

Erst danach wird eine neue Anforderung in Angriff genommen. Die Arbeitsabläufe je Sprint sind dabei immer dieselben, jedoch wird täglich neu priorisiert und die Planung der anstehenden Aufgaben angepasst. Teile der Benutzerdokumentation sind sprintbezogen, andere sind projektbezogen (Installationsanleitung, Konfigurationshilfe, Fehlerfalldokumentation etc.).

Es sollte immer genügend Zeit für Reviews (sprachlich, fachlich) und Tests (technisch) eingeplant sein. Die enge Zusammenarbeit zwischen Produktmanagement, Entwicklung, Tester-Team und Technischer Dokumentation ermöglicht es, Fehlerfälle u.a. in Bedienungsanleitungen bzw. einzelnen Topics (Informationsbausteinen) schneller zu beheben als bei der traditionellen Dokumentationsweise.

Die Technischen Redakteur:innen im agilen Umfeld können wesentlich mehr Einfluss auf Design und Usability der Software nehmen. Dennoch dokumentieren die Redakteur:innen mitunter nur anhand dessen, was sie aus den Konzepten und den Besprechungen erfahren. Denn die zu beschreibende Funktionalität wird ja parallel erst implementiert. Ein Hamsterrad aus Informationsbeschaffung, Dokumentation, Test, Review und Änderungen, das bei sehr gutem Organisationsmanagement gute Ergebnisse erzielen kann.

Einem Unternehmen, das nach agilen Prinizipien entwickelt, dürfte es nicht passieren, dass bei Auslieferung der Software die Dokumentation gänzlich fehlt oder nur teilweise fertiggestellt ist. Vielmehr: Die Software ist erst dann vollständig, wenn die entsprechenden Benutzungsinformationen für produziert und valide erklärt wurden. Da die Entwicklung und die Dokumentation der Software nahezu zeitgleich ablaufen, sind zu beiden Seiten jederzeit Änderungen möglich, aber auch nötig. Bei Auslieferung eines Releases entspricht der Stand der Dokumentation in der Theorie und damit im Idealfall genau dem der Software.

Welche Normen sind für die Softwaredokumentation relevant?

Konkrete gesetzliche Vorgaben zur Erstellung Technischer Dokumentation im Bereich Software gibt es nicht. Doch es gibt einige Normen, die du kennen und gelesen haben solltest und aus denen du einige wichtige Informationen für die Software-Dokumentation ableiten kannst:

• ISO IEC IEEE 26511
  Software und System-Engineering – Anforderungen an Manager:innen von Informationen für Benutzer:innen von Systemen, Software und Services.
• ISO IEC IEEE 26512
  Software und System-Engineering – Anforderungen an Erwerber:innen und Lieferant:innen von Informationen für Benutzer:innen.
• ISO IEC IEEE 26513
  Software und System-Engineering – Anforderungen an Tester:innen und Gutachter:innen der Benutzungsdokumentation.
• ISO IEC IEEE 26514
  Software und System-Enginering – Anforderungen an Designer:innen und Entwickler:innen von Benutzungsdokumentation.
• ISO IEC IEEE 26515
  Software und System-Engineering – Entwickeln von Informationen für Benutzer:innen in einer agilen Umgebung.
• ISO IEC IEEE 15289
  Inhalt von Lebenszyklus-Informationsartikeln (Dokumentation)
• IEC/IEEE 82079-1 Ed. 2
  Erstellen von Gebrauchsanleitungen – Gliederung, Inhalt und Darstellung – Teil 1: Allgemeine Grundsätze und ausführliche Anforderungen.
  → Allgemeine Norm für Technische Redakteur:innen zur Erstellung von Benutzungsinformationen (nicht Software-spezifisch).