Prozessorientierte Dokumentation - Wie geht das?

Bestimmte Softwareprodukte brauchen eine Dokumentation, damit neue Anwender:innen schnell lernen, wie sie mit der Software arbeiten können. Aber wie entsteht diese Dokumentation? Wie lange dauert das?

Zur Software gehört Dokumentation

Ich war vor kurzem auf einem Hackathon mit Entwickler:innen und Anwender:innen einer Unternehmenssoftware. Diese Software ist Pflicht für die Organisation. Allerdings ist der Einsatzbereich deutlich über den ursprünglich gedachten Bereich hinausgewachsen. Es kamen neue Module, neue Funktionen und neue Anwenderkreise hinzu. Darunter sind Anwender, die die Sprache der Softwareoberfläche nicht verstehen.

Um das Einarbeiten zu vereinfachen brauchen wir Anleitungen. Dazu gehören zum Beispiel:

• Produktbeschreibung: Was macht die Software? Wozu setze ich sie ein?
  
• Installationshinweise: Wie bekomme ich die Software auf meinen Rechner? (Sowohl aus Sicht der Anwender:innen als auch aus Sicht der Entwickler:innen)
• Schnellstart: Wie kann ich die wesentlichen Funktionen der Software benutzen?
• Benutzerdokumentation: Wie löse ich meine Probleme mit Hilfe der Software? Was sind die wesentlichen Konzepte?
• Administratorendokumentation: Wie verwalte ich die Software so, dass sie benutzbar bleibt? Wie füge ich neue Anwender hinzu? Wie verwalte ich die einzelnen Komponenten der Software? 
• Entwicklerdokumentation: Wie funktioniert die Software? Wie erweitere ich die Funktionalität?

An dieser Aufzählung sieht man schon, dass es für jede Dokumentation eine Zielgruppe gibt, die bestimmte Bedürfnisse hat. Innerhalb der Zielgruppen gibt es unterschiedliche Niveaus. Es gibt Anfänger:innen und erfahrene Benutzer:innen. Beim Erstellen der Dokumentation müssen wir auf diese Bedürfnisse eingehen. Eine Dokumentation, die keiner liest, ist Verschwendung.

Aber wie entsteht die Dokumentation?

Wie wird Software dokumentiert?

Normalerweise sind technische Redakteur:innen für das Erstellen zuständig. Über technisches Schreiben und technische Dokumentation selbst gibt es viel Literatur. Der Redaktion ist es immer wichtig, dass die Dokumentation vor allem korrekt und konsistent ist.

Krista Van Laan stellt in ihrem Buch über technisches Schreiben eine einfachen Prozess zum Erstellen vor /1, S. 206/:

• Informationen sammeln (gather)
• Erstellung planen (plan)
• Schreiben (write)
• Überprüfen (verify)
• Überarbeiten (redo)

Diese Schritte laufen zyklisch ab. Man kann sie in einem langen oder in vielen kurzen Zyklen laufen lassen. Andrew Etter hat eine kurze Abhandlung über den technischen Prozess geschrieben. /2/

In der technischen Dokumentation verwaltet man die Texte und Abbildungen heute genauso wie Quelltexte in der Softwareentwicklung. Word und Wikis sind als Tools schlecht geeignet, weil man mit ihnen nur ganz schlecht Abläufe automatisieren kann. Markdown und Asciidoc sind zum Erstellen und Verwalten der Texte viel praktischer.

Wenn wir in der Lage sind, die Anleitungen schnell und ohne großen Aufwand anzupassen, gehen wir eins der größten Probleme der Softwareentwicklung an.

Software und damit Dokumentation veraltet

Software, die benutzt wird, verwaltet. Funktionen verändern sich. Es kommen neue Funktionen hinzu und manche Funktionen werden nicht mehr gebraucht. Wenn sich die Software ändert, muss sich auch die Dokumentation verändern. Sie veraltet noch schneller als die Software selbst.

Dazu gibt es zwei Ursachen:

1. Softwareentwicklung und Dokumentation sind häufig voneinander getrennte Prozesse. Tatsächliche Funktionalität und Beschreibungen laufen dann auseinander.
2. Es gibt statische und dynamische Teile in der Dokumentation. Wenn wir diese Anteile nicht voneinander trennen, muss die gesamte Dokumentation ständig angepasst werden.

Agile Teams haben wir die erste Ursache eine Lösung gefunden. In ihrer sog. Definition of Done, einer gemeinsamen Qualitätscheckliste, vereinbaren sie, dass die Arbeit erst fertig ist, wenn auch die Dokumentation aktuell ist.

Für die zweite Ursache nutzen wir eine Technik, die wir schon aus der prozessorientierten Ablage kennen.

Struktur für Dokumentation

In der prozessorientierten Ablage versuchen wir Vorgänge zu bilden, um Dokumente zu bündeln. Gleichartige Vorgänge werden in Prozessen gebündelt. Was abgeschlossen ist, wird archiviert. Diese Prinzipien können wir auch für die Dokumentation übernehmen. Manuela und Georg Reiss verfolgen übrigens in ihrem Praxisbuch IT-Dokumentation einen vergleichbaren Ansatz./3/

Unser Schwerpunkt liegt bei der Anwenderdokumentation. (Installationshinweise und Schnelleinstieg sind meist kurze Dokumente, die schnell aktualisiert sind. Administrator:innen und Entwickler:innen haben auch feste Plätze für ihre Dokumentation und finden sich schnell zurecht.)

Wie könnte man also vorgehen, um die wichtigsten Prozesse der Anwender:innen so zu beschreiben, dass sie sich schnell zurecht finden?

Zunächst legen wir ein paar Prinzipien fest:

1. Unterscheidet Inhalte, die sich häufig ändern und legt sie in getrennten Dokumenten oder Artikeln ab.
2. Haltet die Dokumente oder Artikel kurz.
3. Arbeitet mit Übersichten (Maps of Content) und Querverweisen
4. Wir benennen die Artikel oder Dokumente nach Prozessen und Abläufen
   

Inhalte, die sich häufig ändern:

• Softwareeinstellungen
• Bildschirmoberflächen
• Listen mit Ansprechpartner:innen, die für die Software zuständig sind.
• Listen mit Softwarekomponenten
• Verlaufsdokumentation
• Listen mit Änderungen am System
  

Inhalte, die sich langsamer ändern:

• Basiskonzepte, wesentliche Begriffe
  
• Prozessbeschreibungen

Hier ist eine Beispielstruktur. Diese Struktur kann in einem Verzeichnis oder in einem Wiki abgebildet werden. Die PDF-Dateien könnten auch Webseiten sein.

AKTUELLE DOKUMENTATION

• (Aktuelle übergreifende Dokumentation)
• Installationshinweise.pdf
  
• README.TXT <-- gibt einen Überblick
• Produktbeschreibung.pdf
• Schnelleinstieg.pdf
• 1_Software benutzen
• (Akt. Anwenderhandbuch)
• Basiskonzepte.pdf 
• Übersicht über alle Prozesse.pdf
• Als Anwender am System anmelden.pdf
• Einen Beleg buchen.pdf
• ...
  
• Dokumentation anpassen
• (Aktuelle Quellen)
• 2025-04-14_Steuerliche Änderung
• 2_Software betreiben
• (Akt. Adminhandbuch)
• alle wichigen Betreuungsprozesse als einzelnes Dokument oder eigenen Artikel
• ...
• Dokumentation anpassen
• (Aktuelle Quellen)
• 2025-04-10_Neues Login für Datenbank
• 2025-04-11_Neuer Datenbank Server
  
• 3_Software weiterentwickeln
• (Akt. Entwicklerhandbuch)
• ...

Die Prozesse richten sich nach dem, was die Zielgruppen mit der Software machen. Darunter gibt es Wissensdokumente. Veränderungen werden in eigenen Vorgängen bearbeitet.

Vielleicht helfen diese Hinweise beim Erstellen und Pflegen der Dokumentation. 

Zu diesem Beitrag gibt es eine Fortsetzung darüber, wie man Dokumentation erstellt.

Literaturverweise

• /1/ Laan, Krista Van: The Insider's Guide to Technical Writing. Laguna Hills, Calif: XML Press, 2022. 
• /2/ Etter, Andrew: Modern Technical Writing: An Introduction to Software Documentation, 2016 
• /3/ Reiss, Manuela ; Reiss, Georg: Praxisbuch IT-Dokumentation : Vom Betriebshandbuch bis zum Dokumentationsmanagement – die Dokumentation im Griff. M: Carl Hanser Verlag GmbH  Co KG, 2019.