Dokumentation eine lästige Angelegenheit?

07.05.1982

Die Situation mangelhaft dokumentierter Software in der Praxis; das Unbehagen, Dokumentation schreiben zu müssen; das Problem, mit nicht dokumentierter Software arbeiten zu müssen; die Unmöglichkeit, nicht dokumentierte Software modifizieren, ändern oder anpassen zu müssen.

*Erika Baumann ist freiberufliche DV-Beraterin in München

Teil 1

Würde man heute eine beliebige Zahl von Softwareentwicklern, Programmierern und DV-Planern fragen, was sie von Software-Dokumentation oder zumindest von Programm- Dokumentation halten, man bekäme wahrscheinlich zu hören, daß diese Tätigkeit unbefriedigend ist, weil unproduktiv, und obendrein lästig. Denn Dokumentation ist in den Augen vieler eine Arbeit "für den Papierkorb", "etwas, was doch nicht gelesen wird". Softwareentwickler dokumentieren offensichtlich nicht gerne.

Und auf die Frage "Haben Sie Ihr letztes Programm, Ihr letztes Verfahren oder System ,dokumentiert' ?" würde man voraussichtlich folgende Antworten bekommen: "Dazu haben wir keine Zeit mehr gehabt." Oder: "Das war im Budget nicht mehr drin." Bestenfalls noch: "Ganz am Schluß haben wir schnell noch etwas geschrieben."

Diese Situation findet sich besonders kraß bei Softwareentwicklern, die in der hauseigenen EDV- Abteilung bei einem größeren Anwender tätig sind.

Weniger auffallend ist diese Situation erfahrungsgemäß bei Softwareentwicklern, die im Auftrag eines Hardwareherstellers oder Softwarehauses für einen externen Anwender arbeiten, weil hier häufig die Dokumentation eigens Vertragsgegenstand ist.

Des weiteren muß eingeräumt werden, daß DV- Entwickler, die Software planmäßig erstellen, orientiert an einem "Projektmodell" oder "Phasenkonzept", und dabei nach Software-technologischen Gesichtspunkten vorgehen, sicher eine Menge dokumentieren. Es stellt sich allerdings in der Praxis sehr häufig heraus, daß diese Dokumentationen nicht vollständig und unzureichend sind, was dann die "Situation mangelhaft dokumentierter Software in der Praxis" ausmacht.

Mangelhaft dokumentiert heißt, daß die Beschreibung der Software nicht einheitlich nicht vollständig und nicht durchgängig ist.

Die Beschreibung der fachlichen Aufgabenstellung und der programmtechnischen Umsetzung sind weder strikt voneinander getrennt noch aufeinander abgestimmt.

Die Dokumentationen sind für den Leser, also den Anwender oder das Rechenzentrum häufig nicht lesbar, weil im "EDV-Slang" geschrieben.

Kommentarzeilen zwischen den Statements eines Programms oder ein erläuternder Vorspann im "Programmkopf" können keine Dokumentation ersetzen.

Die Praxis zeigt, daß insbesondere Schnittstellen zwischen einzelnen Programmen aber auch Datenschnittstellen unzureichend beschrieben werden. Das gleiche gilt für die Beschreibung der Ablaufsteuerung in einem größeren Verfahren oder des Steuerflusses in einem Programm.

Die meisten Fehler scheinen jedoch bei der fachlichen Beschreibung gemacht zu werden, das heißt in der Aufgaben- und Problemstellung. Dies führt zu einem erheblichen Bruch in der Gesamtdokumentation.

So könnte man geneigt sein in Anlehnung an die "Software- Krise" der 70er Jahre, von einer "Dokumentationskrise" der 80er Jahre zu sprechen.

Wie kommt es dazu?

Vielen Programmierern "reicht" es, ein Programm einmal zu schreiben, also zu programmieren. Sie möchten das Ganze nicht noch einmal dokumentieren müssen.

Manchen fällt es schwer, etwas zu formulieren und schriftlich festzuhalten.

Dieses Verhalten ist häufig bei Technikern zu beobachten - und Datenverarbeitung ist ein solches Tätigkeitsfeld. Ein Techniker fertigt lieber eine Zeichnung an, als daß er zwei Seiten Text schreibt. Das ist im Sinne "rationeller Dokumentation sicher von Vorteil, nur läßt sich nicht alles in Zeichnungen darstellen, und die Leser, für die die Dokumentationen bestimmt sind, können diese oft nicht ausreichend interpretieren. Das trifft für Hantierungsvorschriften und Bedienungsanleitungen zu, die heute sehr häufig direkt für den Anwender geschrieben werden, der in zunehmendem Maße gleichzeitig Systembediener ist.

Dokumentieren zu müssen, bereitet Softwareentwicklern auch deshalb Unbehagen, weil Dokumentation eine sehr zeitaufwendige Tätigkeit ist. Sie läuft in der Regel in folgenden Schritten ab:

- Entwurf

- Überarbeitung

- 1. Korrektur

- 2. Korrektur

- Vervielfältigung

- Vollständigkeitsprüfung.

Dokumente müssen verwaltet, verteilt und aktualisiert werden.

Der "Erfolg beim Schreiben" kommt also erst sehr spät. Dokumentation hat bei denjenigen, die über "Erfolg" zu befinden haben, häufig gar keinen oder einen sehr geringen Stellenwert.

Ein Softwareentwickler freut sich mehr über ein Programm "das läuft", als über zehn Seiten Dokumentation, weil er dieser ja selber nur mindere Bedeutung beimißt.

In diesem Zusammenhang war bei einem EDV-Praktiker eine sehr extreme Meinung zu hören:

Wer sein Programm dokumentiert, legt seine Arbeit offen und macht sich am Ende ersetzbar, wenn andere sein Programm durchschauen.

Diese Meinung ist hoffentlich ein Einzelfall, zeigt aber, wo die Wurzeln für das allgemeine Unbehagen an der Dokumentation liegen. In der Praxis ist es häufig so, daß der Entwickler gar nicht weiß, für wen er dokumentiert, weil er seine Leser, seine Zielgruppe, nicht kennt und somit auch nicht weiß, wie er schreiben muß. Es ist zu beobachten, daß bei vielen neuen Projekten zu Beginn Richtlinien und Konventionen geschaffen werden - so auch Dokumentationsrichtlinien. Das ist sicher ein guter Vorsatz. Nur trifft man mit diesen Richtlinien meist nicht die eigentlichen Probleme des Dokumentierens, und die Betroffenen wissen die Richtlinien nicht anzuwenden, weil sie darin nicht geschult werden.

Überhaupt scheint die Hauptursache am Unbehagen in der Dokumentation die zu sein, daß Dokumentation nicht gelehrt und gelernt wird. Wer eine Programmiersprache anwenden soll, wird zu einem Kurs geschickt; wer ein Betriebssystem kennenlernen soll, arbeitet sich anhand von Material da hinein; wer Softwareplanung oder Technologie beherrschen soll, besucht einen Lehrgang. Aber wer dokumentieren soll, wird darin nicht unterrichtet.

Der Entwickler gibt im allgemeinen die von ihm erstellte Software aus der Hand und hat dann nichts mehr damit zu tun. Zukünftig wird der Anwender mit dieser Software arbeiten, hantieren und umgehen.

Wird fortgesetzt