Technische Dokumentation: Teil der Lieferung, nicht Nacharbeit

Technische Dokumentation beschreibt ein System so, dass jemand es betreiben, ändern und prüfen kann, ohne den ursprünglichen Entwickler zu fragen. Sie ist Teil der Lieferung und nicht die Aufgabe, die am Ende übrig bleibt. Ihr Umfang richtet sich danach, wer sie später braucht und wofür.

Technische Dokumentation: Umfang und Zweck

Der Zweck ist Handlungsfähigkeit ohne die Person, die etwas gebaut hat. Daran misst sich der Umfang: Beschrieben wird, was jemand wissen muss, um eine Entscheidung zu treffen — nicht, was der Code ohnehin zeigt. Eine Auflistung aller Funktionen mit ihren Parametern ist keine Beschreibung, sondern eine zweite, schlechtere Fassung des Quelltextes.

Wertvoll ist das Gegenteil: die Gründe. Warum liegt die Preisberechnung in einem eigenen Dienst, warum wird eine Bestellung erst nach dem Abgleich mit dem Lager verbucht, welche Fremdsysteme lesen mit. Solche Sätze stehen nirgendwo im Programm und gehen verloren, sobald jemand das Haus verlässt.

Abzugrenzen ist die Beschreibung des Bestands von der Beschreibung des Auftrags. Was gebaut werden soll, steht in der Leistungsbeschreibung; wie das Ergebnis anschließend betrieben und verändert wird, steht in den technischen Unterlagen. Beides zu vermischen, führt dazu, dass nach der Übergabe niemand weiß, welches Dokument den heutigen Stand beschreibt.

Wer die Unterlagen liest

Drei Leserkreise mit unterschiedlichen Fragen:

• Betrieb. Wie wird das System gestartet, überwacht und gesichert, was bedeutet eine bestimmte Meldung, wen erreicht man bei einer Störung.
• Entwicklung. Wie ist das System aufgebaut, welche Entscheidungen liegen zugrunde, wie richtet man eine Arbeitsumgebung ein, wie kommt eine Änderung in den Betrieb.
• Fachabteilung und Prüfung. Welche Regeln gelten fachlich, wo werden personenbezogene Daten verarbeitet, welche Auswertung stammt aus welcher Quelle.

Ein Dokument für alle drei Kreise wird von keinem gelesen. Sinnvoll ist eine kurze Einstiegsseite, die auf die drei Stränge verweist, und je Strang so wenig Text wie möglich.

Was zur Lieferung gehört

Als Mindestumfang haben sich fünf Bestandteile bewährt: ein Überblick über Bausteine und ihr Zusammenspiel; die Beschreibung der Schnittstellen mit Feldern, Fehlerfällen und Zuständigkeiten; eine Betriebsanleitung mit Einstellungen, Sicherung und Wiederanlauf; kurze Vermerke zu den wenigen Entscheidungen, die schwer umkehrbar sind; und eine Anleitung, wie man das System auf einem neuen Rechner zum Laufen bringt.

Der letzte Punkt ist der ehrlichste Test der ganzen Sammlung. Wenn eine Person, die das Projekt nicht kennt, damit eine lauffähige Umgebung herstellt, stimmen die Unterlagen. Scheitert sie an einer undokumentierten Einstellung, fehlt genau dort etwas.

Technische Dokumentation zusammen mit dem Code abnehmen

Unterlagen, die nicht Gegenstand der Prüfung sind, entstehen nicht. Deshalb gehört ihr Umfang in die Kriterien für die Abnahme jeder Etappe: welche Teile geliefert werden, in welcher Form, an welchem Ort. Geprüft wird nicht die Seitenzahl, sondern die Benutzbarkeit — jemand aus dem Haus des Auftraggebers führt einen beschriebenen Ablauf allein anhand des Textes aus.

Denselben Dienst leisten die Unterlagen bei einem Wechsel. Endet eine Zusammenarbeit früher als geplant, entscheidet der Zustand der Beschreibung darüber, ob ein Zwischenstand brauchbar ist; die Rechtslage dazu behandelt der Beitrag zur Kündigung eines Werkvertrags. Zugänge, Repository und Unterlagen liegen aus diesem Grund von Anfang an beim Auftraggeber und nicht beim Anbieter.

Warum Unterlagen veralten

Jede Beschreibung beginnt am Tag ihrer Fertigstellung zu altern, weil sich der Code weiter ändert. Dagegen hilft weniger Disziplin als Nähe: Was neben dem Code liegt und mit derselben Änderung geprüft wird, bleibt eher richtig als eine Datei in einem getrennten Ablagesystem, das niemand öffnet.

Zweitens hilft Verzicht. Je mehr Text eine Änderung nach sich zieht, desto sicherer unterbleibt die Pflege. Deshalb beschreibt man das Beständige — Aufbau, Entscheidungen, Schnittstellen nach außen — und überlässt das Veränderliche dem Code und automatisierten Ausgaben. Eine falsche Beschreibung ist schädlicher als keine, weil ihr jemand glaubt.

Wie wir Unterlagen mitliefern

Bei uns gehören die Unterlagen zum Umfang jeder Etappe der Software-Weiterentwicklung und liegen im Repository des Auftraggebers, neben dem Code, den sie beschreiben. Wir halten fest, was schwer umkehrbar ist und warum, beschreiben Schnittstellen mit ihren Fehlerfällen und prüfen die Anleitung zur Einrichtung, indem eine unbeteiligte Person ihr folgt. Umfang und Form stehen im Angebot; Fragen dazu laufen über unsere Projektleitung. Wie das im Zuschnitt eines Vorhabens aussieht, zeigt die Seite Softwareentwicklung.