Dokumentation - eine lästige Angelegenheit?

25.06.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 8

"Nachdokumentation vorhandener Softwaresysteme - ist das möglich?"

Ansätze, Vorschläge und Möglichkeiten, methodisch, personell und zeitlich vorzugehen. Es mag wie ein Alptraum erscheinen, wenn man daran denkt, ein bestehendes Softwaresystem im nachhinein dokumentieren zu müssen. Denn das ist wohl eine der undankbarsten Aufgaben, die einen Softwareanwender oder -entwickler treffen können. Und dennoch muß diese Tätigkeit häufig genug durchgeführt werden.

"Nachdokumentation" heißt, ein bestehendes Softwaresystem, das entwickelt und getestet ist und sich im Einsatz befindet, nachträglich zu beschreiben. Das widerspricht zunächst allen Regeln heutiger Softwareplanung und Softwaretechnologie.

Nachdokumentation kann aus verschiedenen Gründen notwendig werden, zum Beispiel wenn

- das System geändert oder angepaßt werden muß und diese Änderungen nur durchgeführt werden können, wenn Softwarebeschreibungen vorhanden sind;

- für die Anwendung beziehungsweise Bedienung des Systems vollständige und aktuelle Unterlagen vorhanden sein müssen, was bei einer Übernahme des Systems durch weitere Anwender- oder Bedienerzielgruppen auftreten kann.

Mit der Begründung, warum eine Nachdokumentation notwendig wird, sollten gleichzeitig die Ziele festgelegt werden, was man mit einer solchen Aktion erreichen will. Denn diese können ausschlaggebend sein für die Vorgehensweise bei der Nachdokumentation und die Auswahl zur Verfügung stehender Methoden und Hilfsmittel.

Zunächst muß man sich darüber klar werden, in welchem Zustand sich die Software befindet, die nachdokumentiert werden soll. Dabei sind folgende Situationen denkbar:

Situation 1: Das Softwaresystem ist teilweise dokumentiert, die vorhandenen Unterlagen sind aber unvollständig und nicht aktuel. Im Programmcode sind gegebenenfalls Kommentare enthalten.

Situation 2: Das Softwaresystem ist gar nicht dokumentiert, es sind auch keine Kommentare im Programmcode enthalten. Quellprogrammlisten und Quellprogrammbibliotheken sind jedoch vollständig, aktuell, mögliche Versionsunterschiede sind ausreichend gekennzeichnet.

Situation 3: Das Softwaresystem ist im Quellcode vorhanden, jedoch sind nicht alle Programme auf dem neusten Stand und bereits vorhandene unterschiedliche Versionen sind nicht sauber voneinander getrennt. Teilweise existieren alte und neue Programme nebeneinander, die Quellprogrammbibliotheken sind nicht bereinigt, und die Programmlisten stapeln sich zu einem ungenutzten Haufen Papier.

Sltuation 4: Genauso wie Situation 3, nur sind weder Programmlisten vorhanden, noch stehen die Programme im Quellcode in der Bibliothek zur Verfügung, sondern sind nur im ablauffähigen Objektcode vorhanden. Auch solche Situationen gibt es!

Situation 5: Neben Programmbibliotheken und -listen sind Daten- und Dateibeschreibungen, Formulare zur Datenerfassung und Listenbildschemata vorhanden. Anwenderdaten sind auf Datenträger (Stamm-Datenträger, Sicherungs-Datenträger) oder Protokoll vorhanden (Erfassungs- und Änderungsprotokoll).

Die zuletzt beschriebene Situation ist häufig auch in Kombination mit einer der Situationen eins bis vier zu sehen.

Ausgehend davon, welche der hier beschriebenen Situationen im konkreten Fall vorliegt, und unter welcher Zielsetzung die Nachdokumentation angegangen wird, muß man, um den geeigneten Ansatzpunkt zu finden, fragen, welche Unterlagen vordringlich zu erstellen sind und welche dabei gegebenenfalls als "Nebenprodukte" auch noch anfallen. Unter Umständen könnte auf diese Weise die Dokumentation Schritt um Schritt komplettiert werden. So entstehen zum Beispiel beim Erstellen einer Bedieneranleitung Funktionsbeschreibungen, die auch Bestandteil eines Pflichtenhefts werden können.

Soll rückwirkend die Entwicklungsdokumentation ganz oder wenigstens teilweise erstellt werden, kann gemäß den oben beschriebenen Situationen zum Beispiel folgendermaßen vorgegangen werden:

- Prüfen der vorhandenen Beschreibungsunterlagen gegen die aktuelle Quellcodeliste;

- Extrahieren beschreibungsrelevanter Programmteile aus einer Quellcodeliste;

- Rückumsetzen des Quellprogrammcodes in einen beschreibungsfähigen Pseudo-Code, was bei höheren Programmiersprachen leichter gelingt als bei maschinennahen Sprachen;

- Abbilden der Struktur oder Ablaufsteuermechanismen in einem Programm anhand eines Strukturgenerators. Dies ist jedoch nur möglich, wenn die Programme nach den Grundsätzen der Strukturierten Programmierung oder der Normierten Programmierung erstellt wurden;

- Analysieren des Quellcodes auf Eingabe-, Verarbeitungs-, Ausgabe-Elemente, die meistens die Grundelemente für eine funktionale Beschreibung sind.

Nachdokumentation ist nur über den Quellcode möglich. Wenn dieser nicht mehr vorhanden ist, muß auf eine rückwirkende Entwicklungsdokumentation verzichtet werden.

Häufig werden beim Nachdokumentieren auch die Programmbibhotheken bereinigt und Daten- und Dateibestände überprüft, um aktualisiert zu werden.

Für die oben genannten Arbeitsschritte empfiehlt sich eine maschinelle Unterstützung, die jedoch nicht als Standard-Werkzeug am Markt vorhanden und käuflich ist. Vielmehr müssen solche Hilfsmittel den individuellen Gegebenheiten entsprechend selbst erstellt, das heißt programmiert werden.

Fortsetzung folgt