Direkt zum Hauptbereich

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.

 

Kommentare

Beliebte Posts aus diesem Blog

Microsoft Teams: Die neuen Besprechungsnotizen - Loop-Komponenten

  Haben Sie in letzter Zeit in einer Teams-Besprechung die Notizen geöffnet? Dort sind inzwischen die Loop-Komponenten hinterlegt. Die sind zwar etwas nützlicher als das, was zuvor zur Verfügung stand. Trotzdem ist noch Luft nach oben. Und es gibt sogar einige ernstzunehmende Stolperfallen. Hier ein erster, kritischer Blick auf das was Sie damit tun können. Und auch darauf, was Sie besser sein lassen.

Selbstbewertungsfragen für den Alltag in Arbeitsgruppen aus Sicht von Mitarbeitenden

Welche Fragen können wir Mitarbeiter:innen stellen, um herauszufinden, ob agiles Arbeiten wirkt? Es gibt bereits eine Menge an Fragebögen. Aber ich bin nicht immer zufrieden damit.

Wie lassen sich Ergebnisse definieren? - Drei Beispiele (WBS, CBP und BDN)

Ich habe schon darüber geschrieben, warum das Definieren von Ergebnissen so wichtig ist. Es lenkt die Aufmerksamkeit des Projektteams auf die eigentlichen Ziele. Aber was sind eigentlich Projektergebnisse? In diesem Beitrag stelle ich drei Methoden vor, um leichter an Ergebnisse zu kommen.

Agile Sternbilder: Die Entdeckung kosmischer Agilitäts-Superkräfte

Hast du dich je gefragt, ob dein Sternzeichen deine Fähigkeiten in einer agilen Arbeitsumgebung beeinflusst? In diesem Blogpost tauchen wir ein in die faszinierende Welt der Astrologie und ihre mögliche Verbindung zu modernen Arbeitsweisen. Entdecke, wie die Sterne deine agilen Stärken prägen könnten. Ob überzeugter Agilist oder neugieriger Sternzeichenliebhaber – dieser Artikel kann dir neue Perspektiven eröffnen und vielleicht sogar dein nächstes Teamprojekt inspirieren!

Microsoft Lists: mit Forms und Power Apps komfortabel mobil arbeiten

In meinem Kundenkreis sind viele Menschen, die den Arbeitsalltag nicht vorwiegend auf dem Bürostuhl sitzend verbringen, sondern "draußen" unterwegs sind. Vielleicht in Werkstätten oder im Facility-Management. Es ist so wichtig, dass die Schnittstellen zu den Abläufen im Büro gut abgestimmt sind. Microsoft 365 hat so einiges im Baukasten, man muss es nur finden und nutzen.  In diesem Artikel spiele ich ein Szenario durch, das auf Microsoft Lists, Forms und - für die Ambitionierteren - Power Apps setzt.

Scrum und Hardware: Es kommt auf die Basics an

Man kann Hardwareprodukte agil entwickeln. Zum einen kommt Scrum aus der Hardwareentwicklung. Die Softwerker haben die Hardwarekonzepte auf ihre Situation übertragen. Zum anderen hat Hardwareentwicklung heute ganz viel mit Software zu tun. Gerade in frühen Phasen kann man sich mit Simulationen noch viele Wege offen halten und mehrere Pfade parallel verfolgen. In diesem Beitrag empfehle ich eine Podcastfolge und ein Buch, für alle, die mit der Geschwindigkeit ihrer Hardwareentwicklung nicht zufrieden sind.

Wie Agilität den Kundennutzen steigert - Einige Argumente für Berater:innen

In Zeiten wirtschaftlicher Unsicherheit fragen sich viele, ob agile Beratung noch eine Zukunft hat. Die Antwort liegt in der konsequenten Orientierung am Kundennutzen. Qualität setzt sich durch, wenn sie messbare Verbesserungen bei Umsatz, Kosten und Leistungsfähigkeit bewirkt, anstatt sich in Methoden und zirkulären Fragen zu verlieren. Dieser Artikel zeigt, wie agile Beratung nachhaltige Veränderungen in Unternehmen schafft und warum gerade jetzt gute Berater:innen gebraucht werden, um Organisationen widerstandsfähiger zu machen.

Warum eine Agile Transformation keine Reise ist

Die agile Transformation wird oft als eine Reise beschrieben. Doch dieser Vergleich kann viele Unternehmen in die Irre führen oder Bilder von unpassenden Vergleichen erzeugen. Transformationen sind keine linearen Prozesse mit einem klaren Ziel, sondern komplexe und dynamische Entwicklungen. Dieser Artikel zeigt, warum Agilität kein Weg mit einem festen Endpunkt ist.

Warum bringen Warum-Fragen so wenig?

Frust! Wieder gibt's am Ende des Meetings keine Lösungen, sondern nur Diskussionen darüber, wer was warum verbockt hat. Wieder geht nichts voran. Warum passiert uns das immer wieder? (Ha! Da ist sie wieder, die Warum-Frage.)