Dokumentation wird vielfach noch als Anhängsel an die Kreative Tätigkeit des Programmentwicklers betrachtet. Daß diese Betrachtungsweise nicht dazu geeignet ist, Kosten zu sparen und das tägliche Leben zu vereinfachen, meint Wolfram Bartussek, Geschäftsführer der Prosys GmbH aus Darmstadt-Eberstadt. Er beschreibt im folgenden Beitrag, wie die Dokumentation gehandhabt werden sollte, um einen größtmöglichen, vor allem auch wirtschaftlichen Effekt zu erzielen. Dabei dürfte die Dokumentation nicht als lästiger Zwang aufgefaßt werden, sondern als wertvolle Hilfe für die tägliche Arbeit.

Dokumentieren heißt investieren. Es gilt also, die Kosten-Nutzen-Relation zu optimieren und die mit der Investition verbundenen Risiken zu minimieren.

Zunächst zu den Risiken. Das größte Risiko besteht darin, das Dokumentieren zu unterlassen. Dokumentation ist nicht nur die Beschreibung von Dingen und ihrer Beziehungen, Dokumentation ist ganz wesentlich auch verfaßtes Know-how. Geht der potentielle Verfasser, dann geht mit seinem Kopf auch sein Know-how. Die Folgen sind bekannt und offensichtlich.

Das zweitgrößte Risiko besteht darin, Dokumente zu erstellen, die nie verwendet werden. Die Folgen sind ebenfalls bekannt und offensichtlich: hohe Ausgaben, Papierflut und/ oder überlastete Massenspeicher, wirtschaftlich unbegründbarer Verwaltungsaufwand, nach und nach ausbleibende Pflege, Frustration am Arbeitsplatz und vieles mehr.

Wollen wir investieren, um zu sparen, so müssen wir wissen, wann und wo bei der Produktion und Weiterentwicklung von Programmsystemen Kosten entstehen, die mittels Dokumentation reduzierbar sind. Wir sind also bei der Kosten-Nutzen-Relation.

Vorverlagerung reduziert Kosten

Während der Produktion können schon in den frühen Entwurfsphasen und verstärkt während der Tests Kosten dadurch entstehen, daß nur unscharf definiert wurde, was die Anforderungen an das Produkt sind. Diese Kosten können durch eine Vorverlagerung ("front end investment") reduziert werden. Das erforderliche Dokument ist das Pflichtenheft, Lastenheft oder Leistungsverzeichnis. Es muß vom späteren Anwender beurteilbar, kritisierbar und fortschreibbar sein. Es muß für den Informatiker so strukturiert und so präzise sein, daß eine möglichst direkte Umsetzung in Subsysteme und Programme unterstützt wird.

Die Ersparnisse durch ein gewissenhaft erstelltes Pflichtenheft ergeben sich in folgenden Problembereichen:

- Kommunikation zwischen Anwender und Hersteller,

- Kommunikation unter den Projektmitarbeitern,

- Einarbeitung neuer Projektmitarbeiter,

- Projektleitung,

- Gewährleistung.

Das Pflichtenheft muß fortschreibbar sein und auch während der Entwicklung weitergeführt werden, sonst entsteht ein Dokument, das nach kurzer Zeit seinen Gebrauchswert verliert. Eine weitere wichtige Maßnahme zum Schutz der Investition "Pflichtenheft" ist das Einarbeiten eines kleinen, gut ausgearbeiteten Begriffslexikons.

Es enthält die Definition aller Begriffe, die bei der Entwicklung des Pflichtenheftes Anlaß zu Mißverständnissen zwischen Anwender und Hersteller gaben. Die Begriffssammlung wird während der Produktion des Programmsystems fortgeschrieben.

Noch ein Wort zum Pflichtenheft. Akzeptieren Sie die Aussage: Jedes System ist ein Modul in einem umfassenden System. Fertigen Sie für jeden Modul, auch systemintern, ein (eventuell reduziertes) Pflichtenheft an. Bedenken Sie, daß ein Programm letztlich nichts anderes als ein Pflichtenheft für den Rechner selbst ist: Die Vorschrift, unter welchen Voraussetzungen er welche Ergebnisse erzielen soll.

Es wird klar: Am meisten kann man durch Dokumentation dann sparen, wenn man sie als Mittel zum Entwurf nutzt. Die Dokumentation ist dann notwendigerweise vor den Programmen da.

Erhebliche Kosten durch Zeitverluste entstehen dann, wenn der Projektleiter vorübergehend und/oder teilweise den Überblick verliert. Das wird nur selten und ungern eingestanden. Die häufigste Ursache indes ist offensichtlich: fehlende oder unbrauchbare Dokumentation.

Welche Dokumente braucht der Projektleiter, um ein Softwareprojekt im Griff zu behalten?

An erster Stelle stehen die oben beschriebenen Pflichtenhefte für alle Subsysteme (= Module) des angestrebten Programmsystems. Weitere wichtige Dokumente sind: Entscheidungsdokumentation, Beschreibung der Systemstrukturen, Quellprogramme, Übersetzungs-, Binde- und Ablagehilfen, Testpläne, -daten und -ergebnisse und last not least alle Planungshilfen zur Termin-, Arbeits-, Personal- und Kapazitätsplanung wie sie allgemein bei komplexen Projekten eingesetzt werden.

Dokumentation als Mittel zum Entwurf

Entscheidungsdokumentation: Häufig wird viel Zeit damit verloren, daß wichtige Erkenntnisse mehrfach gewonnen werden müssen, weil sie nicht beim ersten Mal in einem dafür vorgesehenen Dokument festgehalten wurden. Die Dokumentation einer Entscheidung enthält den Betreff, die erwogenen Alternativen, die Kennzeichnung der ausgewählten Alternative und die Begründung dafür. Nur wichtige, schwer durchschaubare oder einmal strittig gewesene Entscheidungen sollten so dokumentiert werden.

Systemstrukturen:

Besonders, um neue Mitarbeiter in einem Projekt effizient einarbeiten zu können, aber auch für die Vergabe der Teilarbeiten sind Überblicke über die Systemstrukturen vorteilhaft. Diese Dokumente können häufig sehr kompakt gehalten werden (wenige Seiten) sollten aber stets vorhanden sein.

Programme und Tests:

Dokumente wie Quellprogramme, Übersetzungs-, Binde- und Ablagehilfen fehlen auch in schlecht dokumentierten Systemen nicht. Anders verhält es sich mit Testunterlagen. Diese Dokumente, die jeweils die Entwicklung eines Moduls oder Systems abschließen, leiten über zur Betrachtung der Dokumentation in der Phase der Pflege und Weiterentwicklung.

Bekanntlich entstehen während der Pflege und Weiterentwicklung langfristig gesehen bei weitem die höchsten Kosten während des Bestehens eines Programmsystems. Weiterentwicklung und Pflege:

Es stellt sich hier die Frage, wie die bis jetzt erstellten Dokumente erneut und langfristig genutzt werden können. Alle Erweiterungen und Änderungen sollten an erster Stelle im jeweiligen Pflichtenheft des betroffenen Moduls eingearbeitet werden. Wenn wir langlebige Produkte herstellen und ihre "Gesundheit" erhalten wollen, müssen wir alles vermeiden, was zu einem Verfall der anfangs eingeführten Strukturen führen könnte. Die Devise ist also Strukturerhalt.

Dazu muß ein gewisser "Dienstweg" eingehalten werden. Er führt über die jeweils autorisierte Änderung oder Erweiterung im Pflichtenheft, eventuell daraus resultierende Änderungen in der Entscheidungsdokumentation und die Beschreibung der Systemstrukturen schließlich zu den Quellprogrammen und oben genannten nachfolgend erstellten Dokumenten.

Welche Kosten kann man so sparen?

Häufig betrifft eine Änderung oder Erweiterung keine grundlegende Eigenschaft. Daraus folgt, daß viele Dokumente und Teile davon unberührt bleiben. Man kann wegen der bisher erhaltenen Strukturen genau sagen, welcher Modul betroffen ist. Vor allem der sonst oft so hohe Testaufwand ist begrenzbar und kalkulierbar. Des weiteren kommt es seltener zu sogenannten "Huckepacklösungen".

"Ripple effects" werden eingegrenzt

Eine auf Übersichtlichkeit und Fortschreibung ausgelegte Dokumentation erhöht die Effizienz des Personals zur Pflege und Weiterentwicklung eines Systems. Dies schlägt sich vor allem in reduzierten Suchzeiten, eingrenzbarem Änderungsaufwand und klar vorhersagbaren Auswirkungen auf den Rest des Systems nieder (Eingrenzung von "ripple effects"). Einarbeitungszeiten können deutlich reduziert werden.

Soweit zur Dokumentation als Schreibtischwerkzeug. Soll sie durch Programmsysteme ("programmierte Werkzeuge") unterstützt werden, so ergeben sich folgende Anforderungen:

1. Die Erstellung von Pflichtenheften muß unterstützt werden. Es müssen Kapitelstrukturen definiert werden können. Es müssen Formulare, Masken oder Schemata definiert werden können. Die Datenerfassung über derart definierte Schemata muß unterstützt werden. Das Erstellen von Querverweislisten für Stichworte (Indizes) muß unterstützt werden.

2. Die Erstellung von Entscheidungsdokumentation und vor allem deren Verwaltung muß unterstützt werden.

3. Die Dokumentation der wichtigsten und häufigsten Systemstrukturen wie Hierarchien, Bäume, einfache Netze sollte alphanumerisch wie auch graphisch unterstützt werden. Restriktionen für spezielle Strukturen sollten frei definierbar sein.

4. Die Verwaltung aller Programm-und Testdokumente sollte in die Gesamtdokumentation integriert sein.

5. Stichwortverzeichnisse sollten über alle Dokumente hergestellt werden können. Dies ist besonders für alle Verbindungen zwischen Quellprogrammen (Kommentierung) und den Pflichtenheften wichtig.

6. Die Verwaltung der Gesamtheit der erstellten Dokumente sollte unterstützt werden. Die Buchhaltung von Versionen und Produktmustern muß unterstützt werden.

Natürlich kann in diesem Text nur von außen auf die wichtigsten Punkte hingewiesen werden: sozusagen auf das Unverzichtbare. Wichtig ist, daß wir Dokumentation nicht als lästigen Zwang auffassen, so wie die Mahnung aus dem Kindesalter: Nun hast Du den ganzen Tag schön gespielt, nun mußt Du auch aufräumen.

Nachdokumentieren führt selten zu Ersparnissen.

Wir sollten mittels Dokumentation entwerfen und mit ihrer Hilfe die anfangs eingeführten Strukturen erhalten, dann sparen wir am meisten.