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 nutzerfreundlich noch hilfreich. Leider allerdings auch nicht selten.

Stechen Sie mit Ihren Anleitungen aus der Menge heraus, lernen Sie in diesem Artikel die Basics für gute Softwareanleitungen und erfahren Sie, welche Normen und Richtlinien für Software-Dokumentationen relevant sind.

Eine gute Technische Kommunikation unterstützt den Benutzer dabei seine 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 Ihre Nutzer 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 Sie Ihre internen Aufgaben, Entwicklungsschritte und Prozessabläufe dokumentieren. 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 Sie interne Software-Beschreibungen erstellen sollten

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

„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 Ihrer Produkte

Dokumentieren Sie,

• 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 Software-Dokumentation unabdinglich machen

Jede Software, die für ein Produkt größeren Umfangs entwickelt wird, erfordert mehrere Entscheidungen. In der meist langen Designphase mit wechselnen Mitarbeitern und grundsätzlich vielen involvierten Personen stellen sich schon beim bloßen Skizzieren des grafischen Designs, der Benutzerinteraktion, 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 der Endnutzer mit der Software gut umgehen kann und sie versteht. Die Dokumentation von Software für extern ist stark zielgruppengebunden.

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

Welche Anforderungen gibt es an Software-Informationsprodukte?

Achten Sie 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 den Anwendenden zielführend bei der Lösung seiner Aufgabe.
• Navigieren den Benutzer mittels durchdachter Navigationskonzepte zum für ihn relevanten Topic.
• Bieten eine umfassende Suchfunktion.
• Verwenden eine konsistente und dem Benutzer 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 sollten Sie Ihre 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 von Software eine besondere Dokumentation in bestimmter Form bereitzustellen. Jedoch ist der Produkthersteller immer für sein gesamtes Produkt verantwortlich:

• Der Hersteller von Software als eigenständiges Produkt ist verantwortlich im Sinne des Vertragsrechst (von diesen Software-Produkten geht in der Regel nur ein sehr geringes bis kein Sicherheitsrisiko aus, Bsp.: Bildbearbeitungs-Software).
• Der Hersteller von Software als Bestandteil eines Produkts ist 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 leistet der Hersteller mit dem Verkauf und der Auslieferung von Software eine Gewähr für sein 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“ finden Sie ü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 voraus.

Wie Sie agil dokumentieren können

Bei der agilen Dokumentation wird, bedingt durch die Faktoren Zeit und Aktualität, deutlich weniger Dokumentation erzeugt als bei traditionellen Dokumentationsprozessen. Dennoch erwartet der Endnutzer der Software eine qualitativ gleichwertige Benutzerdokumentation, die ihn 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 dem Kunden/Endbenutzer der Software. Durch regelmäßiges Feedback vom Kunden zur Software und zur Dokumentation wird die Qualität gesichert und das Ergebnis geliefert, das den Anforderungen des Anwenders 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.

Der Technische Redakteur im agilen Umfeld kann wesentlich mehr Einfluss auf Design und Usability der Software nehmen. Dennoch dokumentiert der Redakteur mitunter nur anhand dessen, was er aus den Konzepten und den Besprechungen erfährt. 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 Benutzerinformationen 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 Sie kennen und gelesen haben sollten und aus denen Sie einige wichtige Informationen für die Software-Dokumentation ableiten können:

ISO IEC IEEE 26511
Software und System-Engineering – Anforderungen an Manager von Informationen für Benutzer von Systemen, Software und Services.

ISO IEC IEEE 26512
Software und System-Engineering – Anforderungen an Erwerber und Lieferanten von Informationen für Benutzer.

ISO IEC IEEE 26513
Software und System-Engineering – Anforderungen an Tester und Gutachter der Benutzerdokumentation.

ISO IEC IEEE 26514
Software und System-Enginering – Anforderungen an Designer und Entwickler von Benutzerdokumentation.

ISO IEC IEEE 26515
Software und System-Engineering – Entwickeln von Informationen für Benutzer 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 Redakteure zur Erstellung von Benutzerinformationen (nicht Software-spezifisch).