Brauchbare Software-Dokumentation besteht aus vier getrennten Textsorten für vier Adressaten: Anwenderanleitung, Betriebshandbuch, Entwicklerdokumentation und Entscheidungsprotokolle. Sie liegt neben dem Code, wird bei jeder Auslieferung mitgeprüft und bleibt bewusst knapp. Das beste Qualitätsmaß ist der Onboarding-Test: Kommt eine neue Person in ihrer ersten Woche allein zurecht?
Für wen schreiben Sie eigentlich?
Der häufigste Fehler ist ein einziges Dokument für alle. Darin sucht die Sachbearbeiterin zwischen Serverpfaden nach der Anleitung für die Tagesabrechnung, und die Administratorin blättert durch Klickstrecken, um eine Konfigurationsdatei zu finden. Am Ende benutzt es niemand.
Vier Adressaten haben grundverschiedene Fragen. Wer die Software bedient, will wissen, wie eine Aufgabe erledigt wird. Wer sie betreibt, will wissen, was zu tun ist, wenn etwas klemmt. Wer sie weiterentwickelt, will wissen, wie sie aufgebaut ist. Und wer sie verantwortet, will wissen, warum sie so ist, wie sie ist.
- Anwenderanleitung: aufgabenorientiert, entlang echter Arbeitsabläufe, nicht entlang der Menüstruktur.
- Betriebshandbuch: Installation, Konfiguration, Sicherung, Wiederherstellung, Überwachung, Störungsfälle mit konkreten Schritten.
- Entwicklerdokumentation: Aufbau der Bereiche, Datenmodell in Grundzügen, lokale Einrichtung, Auslieferungsweg, Besonderheiten.
- Entscheidungsprotokolle: welche Weggabelung wann wie entschieden wurde und aus welchem Grund.
Ein Logistikdienstleister, der ein Tourenplanungssystem betreibt, braucht alle vier — aber nie in einem Dokument und selten von derselben Person geschrieben. Die Anwenderanleitung entsteht am besten mit jemandem aus der Disposition, das Betriebshandbuch mit der IT.
Was gehört in ein Architecture Decision Record?
Ein Architecture Decision Record, kurz ADR, ist eine einseitige Notiz zu einer einzelnen technischen Entscheidung. Es beantwortet vier Fragen: Welche Situation lag vor? Welche Optionen standen zur Wahl? Wofür haben wir uns entschieden? Welche Folgen nehmen wir dafür in Kauf?
Der Nutzen zeigt sich achtzehn Monate später, wenn jemand fragt, warum die Anwendung keine eigene Benutzerverwaltung hat oder warum Dokumente außerhalb der Datenbank liegen. Ohne Notiz beginnt eine Diskussion von vorn, oft mit dem Ergebnis, dass eine gute Entscheidung aus Unkenntnis rückgängig gemacht wird.
ADRs werden nicht nachträglich korrigiert. Ändert sich die Lage, schreiben Sie ein neues und verweisen auf das alte. Diese Kette ist bei einer Übergabe wertvoller als jedes Architekturdiagramm, weil sie den Denkweg zeigt und nicht nur den Endstand.
Ein Diagramm zeigt, wie die Software heute aussieht. Ein Entscheidungsprotokoll erklärt, warum sie nicht anders aussieht.
Warum gehört Dokumentation neben den Code und in die Auslieferung?
Dokumentation in einem Textverarbeitungsprogramm auf einem Netzlaufwerk veraltet, weil sie von der Entwicklung getrennt ist. Niemand denkt beim Ändern einer Funktion an eine Datei, die er zuletzt vor acht Monaten geöffnet hat.
Legen Sie Entwickler- und Betriebsdokumentation deshalb als einfache Textdateien in dasselbe Verzeichnis wie den Quellcode. Sie wandern damit durch dieselbe Prüfung wie jede Codeänderung, und die Frage „Muss dazu die Dokumentation angepasst werden?“ wird Teil des normalen Ablaufs statt einer separaten Erinnerung.
Nehmen Sie zusätzlich einen Punkt in die Auslieferungsliste auf: Keine Version geht produktiv, ohne dass geprüft wurde, ob die Dokumentation dazu passt. Das ist eine Minute Aufwand pro Auslieferung und der wirksamste Einzelschritt gegen Veralten. Die Anwenderanleitung darf dagegen dort liegen, wo Anwender sie finden — meist in der Anwendung selbst oder im Intranet.
Sind Screenshots und Videos die Mühe wert?
Bildschirmfotos sind hilfreich und gleichzeitig die größte Wartungslast in jeder Anleitung. Jede Änderung an der Oberfläche entwertet sie, und weil Bilder nicht durchsuchbar sind, fällt lange niemandem auf, dass die gezeigte Schaltfläche nicht mehr existiert.
- Setzen Sie Bildschirmfotos nur dort ein, wo Text allein wirklich nicht trägt — etwa bei einer schwer auffindbaren Stelle in der Oberfläche.
- Zeigen Sie Ausschnitte statt ganzer Bildschirme; Ausschnitte überstehen Layoutänderungen deutlich länger.
- Benennen Sie Bedienelemente im Text ausdrücklich, damit die Anleitung auch ohne Bild verständlich bleibt.
- Führen Sie eine Liste, welche Anleitungsseiten Bilder enthalten, damit nach einer Oberflächenänderung klar ist, was zu prüfen ist.
Kurze Videos von zwei bis drei Minuten funktionieren gut für Abläufe, die man einmal versteht und dann kann — die Ersteinrichtung, eine wiederkehrende Monatsroutine. Für Nachschlagen taugen sie schlecht, weil niemand eine Stelle in einem Video sucht. Eine Bildungseinrichtung, die ein Prüfungsverwaltungssystem einführt, fährt mit einem Video zum Semesterstart plus einer knappen Textanleitung besser als mit einem vierzigseitigen Handbuch.
Woran erkennen Sie, dass die Dokumentation taugt?
Verlassen Sie sich nicht auf das Urteil derer, die sie geschrieben haben — sie kennen das System und lesen jede Lücke unbewusst mit. Nehmen Sie stattdessen eine Person, die neu dazukommt, und beobachten Sie ihre erste Woche.
Der Onboarding-Test läuft in drei Stufen. Am ersten Tag: Kann sie die Anwendung lokal starten, ohne jemanden zu fragen? In der ersten Woche: Kann sie eine kleine Änderung bis in die Testumgebung bringen? Nach zwei Wochen: Kann sie erklären, warum zentrale Bausteine so gebaut sind?
Jede Stelle, an der sie nachfragen muss, ist eine Lücke — und wird von ihr selbst geschlossen, nicht vom Autor. Wer neu ist, sieht genau das, was Erfahrene übersehen. Nach unserer Projekterfahrung ist dieser Ablauf die günstigste Qualitätssicherung, die es für Dokumentation gibt.
Ist mehr Dokumentation besser?
Nein, und zwar aus einem einfachen Grund: Umfang und Aktualität stehen in umgekehrtem Verhältnis. Zweihundert Seiten kann niemand pflegen, also veralten sie. Veraltete Dokumentation ist schlimmer als keine, weil sie Vertrauen erzeugt und dann in die Irre führt.
Setzen Sie sich eine Obergrenze und halten Sie sie ein. Zwanzig bis dreißig Seiten Entwicklerdokumentation reichen für die allermeisten mittelständischen Anwendungen aus, wenn sie die richtigen Dinge enthalten. Was der Code selbst lesbar ausdrückt, gehört nicht ins Dokument.
Dokumentieren Sie bevorzugt das, was man dem Code nicht ansieht: Absichten, verworfene Wege, Abhängigkeiten zu Fremdsystemen, fachliche Sonderfälle mit ihrer Begründung. Eine ungewöhnliche Rundungsregel, die aus einer Prüfvorgabe stammt, gehört erklärt — die Schleife darüber nicht.
Was brauchen Sie beim Wechsel des Dienstleisters?
Eine Übergabe scheitert selten am Quellcode. Sie scheitert an dem, was nur im Kopf des bisherigen Teams existiert: welcher Dienst nachts läuft, wo die Zertifikate liegen, warum ein bestimmter Auftrag manuell nachbearbeitet werden muss, wen man beim ERP-Partner anruft.
- Eine vollständige Liste aller Umgebungen mit Zugängen, Zuständigkeiten und Ablaufdaten von Zertifikaten und Schlüsseln.
- Eine Aufstellung externer Abhängigkeiten: Fremddienste, Lizenzen, Verträge, Ansprechpartner, Kündigungsfristen.
- Eine nachvollziehbar getestete Anleitung, wie man aus dem Nichts eine lauffähige Umgebung herstellt.
- Die Sammlung der Entscheidungsprotokolle, damit das neue Team nicht bei null anfängt zu diskutieren.
- Eine ehrliche Liste bekannter Schwachstellen und offener Punkte statt einer geschönten Zustandsbeschreibung.
Vereinbaren Sie außerdem, dass die Anleitung zur Umgebungsherstellung mindestens einmal jährlich von jemandem ausgeführt wird, der sie nicht geschrieben hat. Eine ungetestete Anleitung ist eine Behauptung.
Wie verankern Sie Dokumentation im Vertrag?
Formulierungen wie „angemessene Dokumentation“ sind wertlos, weil sie im Streitfall nichts bedeuten. Benennen Sie die geschuldeten Dokumente einzeln, legen Sie Format und Ablageort fest und knüpfen Sie sie an die Abnahme: Ohne die vereinbarten Unterlagen gilt eine Leistung nicht als abgenommen.
Zwei Ergänzungen lohnen sich. Erstens eine Aktualisierungspflicht im Wartungsvertrag, damit die Unterlagen mit jeder größeren Änderung mitwachsen. Zweitens die Zusage, dass alle Dokumente in einem offenen, durchsuchbaren Format übergeben werden und nicht in einem Werkzeug liegen, das mit dem Dienstleister endet.
Rechnen Sie mit etwa fünf bis zehn Prozent des Projektbudgets für Dokumentation, die diesen Anspruch erfüllt. Das ist kein Aufschlag für Papier, sondern der Preis dafür, dass Ihr System auch ohne die Menschen funktioniert, die es gebaut haben.
Legen Sie zusätzlich fest, wer die Unterlagen abnimmt. Eine Abnahme durch die Projektleitung, die alles ohnehin weiß, prüft wenig. Sinnvoller ist, dass eine Person aus dem Betrieb das Betriebshandbuch abnimmt und eine Person aus dem Fachbereich die Anwenderanleitung — jeweils, indem sie damit eine echte Aufgabe erledigt und nicht, indem sie das Dokument überfliegt.
Ein letzter Punkt betrifft die Sprache. Wenn Ihr Team auf Deutsch arbeitet, gehören Anwenderanleitung und Betriebshandbuch auf Deutsch, auch wenn die Entwicklerdokumentation englische Fachbegriffe verwendet. Eine Anleitung in einer Sprache, in der die Anwenderinnen nicht denken, wird nicht gelesen — unabhängig davon, wie gut sie geschrieben ist.