Dokumentation: Nach wie vor ungeliebt und oft vergessen

03.08.1984

Als ungeliebtes Stiefkind geistert die Dokumentation immer noch durch die meisten Unternehmen. Die Datenverarbeiter schieben sie vor sich her oder liefern sie mit viel Murren oft erst Monate nach Beendigung der Programmierungsarbeit nach. Das heißt häufig wird lediglich aus der Erinnerung eine Aufzeichnung der Abwicklungssystematik durchgeführt. Änderungen fließen danach zumeist nicht mehr ein. Hans-Joachim Mährländer von der Gesellschaft für Moderne Organisationsverfahren vertritt die Auffassung, daß Dokumentationsprobleme nicht isoliert betrachtet werden können. Konstatiert der Frankfurter DV-Berater: "Der Dokumentationsschwirigkeiten Herr zu werden, heißt, die Systementwicklung insgesamt in den Griff zu bekommen."

Hans Keutgen

GEI Gesellschaft für Elektronische Informationsverarbeitung, Aachen

Dokumentation war und ist mancherorts auch heute noch ein leidiges Thema. Oft wurde sie mit viel Murren Monate nach Beendigung der Programmierungsarbeiten nachgeliefert, oder die Entwickler tragen auch heute noch ihr Wissen in ihrem Gedächtnis mit sich herum. Ganz zu schweigen davon, daß "Nachdokumentation" von existenter Software in aller Regel ein katastrophales Niveau hat. Andererseits weiß jeder, daß personenunabhängige Wartung von Software nur auf der Grundlage einer vernünftigen Beschreibung erfolgen kann.

Wesentliche Feststellungen sind dabei, daß überhaupt Softwaredokumentation erstellt werden muß und nur entwicklungs- und wartungsbegleitende Dokumentation sinnvoll ist.

Wie können beide Forderungen realisiert werden? Damit Mitarbeiter Dokumentation liefern, müssen sie vom Sinn dieser Tätigkeit überzeugt sein, und Dokumentieren darf nicht durch rein manuellen Arbeitsstil verleidet werden.

Die Notwendigkeit sinnvoller Dokumentation läßt sich am besten dadurch nachweisen, daß man überzeugte "Dokumentationsmuffel" für bestimmte Zeit mit der Pflege von undokumentierten und von ausgesucht gut dokumentierten Programmen beschäftigt. Wichtig ist aber außerdem, daß die Dokumentation nach einheitlichen Richtlinien abfaßbar ist. Dabei wird es nicht für alle Anwendungsbereiche eine einheitliche Form geben, aber sinnvoll ist wohl für jeden Dv-Anwender die Schaffung eines firmeninternen Standards. Als Beispiel können dabei sicher Vorlagen von Unternehmen aus verwandten Branchen dienen.

Werkzeuge zur Hilfestellung bei der Dokumentationserstellung sind inzwischen in vielfältiger Form auf dem Markt. Sie reichen von reinen Textverarbeitungshilfen bis zu vollständigen Softwareentwicklungsumgebungen. Je vollständiger der Entwicklungsansatz ist, desto aussagekräftiger ist bei richtigem Einsatz auch die Dokumentation. Darüber hinaus entsteht eine entwicklungsbegleitende Dokumentation, wodurch die zweite Forderung automatisch miterfüllt wird.

Es dürfte dennoch sehr schwierig sein, einen "kunstschaffenden" Programmierer ohne große Ausbildungsinvestition und ohne- Demonstration des Erfolges auf den Weg der Tugend zu bringen. Deshalb empfehle ich, nicht zu versuchen, alle Stufen in einem Satz überspringen zu wollen. Eine sinnvolle Abstufung könnte für den Anwender, der noch keine zwingende Dokumentation eingeführt hat, folgender Vorschlag sein:

- Einführung einer Dokumentationsrichtlinie (mit Beispielen) und gleichzeitig Festlegung eines einfachen Werkzeuges zur Dokumentationserstellung,

- Motivation und Einführung eines einfachen Softwareentwicklungswerkzeugs (etwa Struktogrammgenerator, Pseudocode),

- Auswahl eines Methodensystems zur Entwicklungsunterstützung,

- Einsatz des Werkzeugsystems.

Sicherlich erscheinen heutige Systeme, die die entwicklungsbegleitende Dokumentation automatisch erzeugen für viele DV-Anwender noch sehr teuer. Aber die Kosten für viele vertane Tage und Wochen für nicht vorhandene oder fehlerhafte Dokumentation respektive fehlgeschlagene Entwicklungen sollten mit ins Kalkül gezogen werden.

Wolfgang Koppmeyer

Org./DV-Leiter Leybold-Heraeus, Hanau

Die Dokumentation von DV-Projekten ist bei allen Unternehmen ein ungeliebtes Stiefkind. An dieser Situation hat sich in den letzten fünf Jahren nichts geändert. Jeder spricht über die Dokumentation, aber keiner mag sie und keiner macht sie. Wenn man über Dokumentation von realisierten Projekten redet, wird fast ausschließlich über die Programm-Dokumentation diskutiert. Aber ein Projekt besteht nicht nur aus Programmen.

Das Rechenzentrum muß über die periodische Abwicklung des Programmes wachen. Die Organisationsabteilung beschafft die Formulare und gibt der Fachabteilung Handhabungshinweise. Die Treuhandgesellschaft, die die Buchprüfung durchführt, will genau wissen, welche Materialbewertungsvorschriften dem Programm zugrunde liegen. Und letztendlich will sich der Vertriebsleiter oder ein neuer Auszubildener über das eingeführte Vertriebsverfahren informieren. Es sind also mehrere Ebenen unterschiedlicher Dokumentationsart für verschiedene Verantwortlichkeitsebenen zu berücksichtigen. Deshalb gibt es eine Organisationsdokumentation, Programmdokumentation, Benutzerhandbuch (Nachschlagewerk, Organisationsanweisung), Kontroll-Dokumentation, Rechenzentrums-Dokumentation.

Die verschiedenen Arten werden im überwiegenden Fall nachdokumentiert, das heißt, wenn ein Projekt lange abgeschlossen ist, macht man aus dem Gedächtnis eine Aufzeichnung der durchgeführten Abwicklungssystematik. Dann bleibt die Dokumentation über Jahre so erhalten, die Änderungen fließen meist nicht ein.

Es hat sich bei den Projekten noch nicht durchgesetzt, daß eine Paralleldokumentation (vor und bei der Programmierung wird gleichzeitig eine angepaßte Dokumentation erstellt) erfolgt.

Fast immer steht ein guter Programmierer auf Kriegsfuß mit den Dokumentationsvorschriften. Daran hat sich auch nichts geändert, als große Unternehmen eine eigene Dokumentations-Mannschaft aufbauten und eine Dokumentations-Philosophie einkauften. Denn alle Dokumentationshilfen sind teuer, unzureichend und nur als Teilhilfen einzusetzen.

Will man heute mit einer Dokumentations-Systematik anfangen, so wird das Personal für solche fachspezifische Aufgaben von den Geschäftsleitungen schlechter als je zuvor genehmigt. Auch die Prüfungsgesellschaften, die mit großen Unternehmen (wie MBB in München) nach Grundsätzen der, "ordnungsmäßigen Buchführung" eine Dokumentations-Systematik erarbeitet haben, können den für eine exakte Arbeit notwendigen Zeitaufwand in anderen Unternehmen nicht realisieren. Auch bleibt meistens die Frage unbeantwortet, was man mit alten Programmen macht. Für diesen Komplex akzeptiert man meist halbherzige Lösungen.

Alle bekannten Dokumentationshilfen beziehen sich auf zwei Gesichtspunkte:

- Programmablaufpläne nicht mehr zu zeichnen, sondern von erstellten Quellenprogrammen abzuleiten (beispielsweise Quickdraw).

- Die Texte einer Dokumentation mit einem Textsystem (zum Beispiel Opus) am Bildschirm zu schreiben.

Alle diese eingesetzten Hilfsmittel sind zu aufwendig und zu teuer.

Bevor man eine projektbegleitende Dokumentation betreiben kann, muß eine Problemlösungs-Systematik ähnlich der Hipo-Technik (hierarchy input process output) eingesetzt werden. Die Hipo-Technik beruht auf der Erkenntnis, daß man von den gewünschten Ergebnissen eines Organisationssystems ausgehen muß, um seine notwendigen Funktionen und die erforderlichen Eingabedaten zu bestimmen. Diesen Grundstock braucht erst einmal jeder, der mit der Dokumentation betraut wurde und selbstverständlich auch jeder DV-Koordinator, Organisator oder Systemanalytiker. Das nächste Problem muß in der Text-Schreib-Problematik gesehen werden. In der Großdatenverarbeitung gibt es bis heute kein brauchbares, einfaches Hilfsmittel zur Lösung der vielfältigen Dokumentations-Texterstellung. Bisher wird es in zu vielen Unternehmen abgelehnt, ein CTV (Computer-Text-Verarbeitungspaket) einzusetzen. Die IBM-Meinung herrscht vor, daß Textverarbeitung vom PC oder der Textverarbeitungs-Hardware (IBM 8100, IBM 4520 etc.) erstellt werden soll. Hier bei der Dokumentation liegt aber wieder der klassische Fall auf dem Tisch, wo integrierte Lösungen nicht ohne Großdatenverarbeitungs-Einheiten aufzubauen sind. Deshalb sollte man sich vorrangig mit dieser Problematik beschäftigen und das DV-Textpaket "Mantext" oder "Edit" für die Dokumentation anpassen.

Der wichtigste Faktor bei der Dokumentationserstellung ist der menschliche Geist. Die Dokumentation besteht zum überwiegenden Teil aus Texten, Tabellen und Grafiken. Das bedeutet, daß eine journalistische Begabung der wesentliche Faktor für die Dokumentationserstellung darstellt. Für eine solch spezialisierte Ausbildung haben wir in unseren DV-Fachabteilungen nichts getan. Hier wäre es sinnvoll, wenn sich Unternehmensberatungen um eine Hilfestellung bei den Aufgaben kümmern würden. Für viele Berater mit journalistischen Fähigkeiten wäre hier ein neues Aufgabengebiet zu erschließen, um die Dokumentation von DV-Verfahren auf den Stand einer Bedienungsanleitung für Software-Nutzer zu heben. Werden solche Hilfestellungen nicht geleistet, werden nach meiner Meinung die DV-Bereiche auch nicht in den nächsten fünf Jahren aus eigener Kraft brauchbare Dokumentationen - abgestimmt auf die Forderung der Anwender - aufbauen können.

Hans-Joachim Mährländer

GMO Gesellschaft für moderne Organisationsverfahren mbH & Co., Geschäftsstelle Frankfurt

Warum ist Dokumentation auch heute noch im Schatten der Megabyte- und MIPS-Maschinen - im Unternehmen ein Thema? Weil es diese Problematik isoliert gar nicht gibt. Denn Dokumentation ist kein einzelner Phasenschritt - möglichst weit hinten im Projekt. Dokumentation ist vielmehr Systementwicklung schlechthin oder anders ausgedrückt, sie muß projektbegleitend erfolgen.

Es ist anzuraten, aber leider noch nicht selbstverständlich, das Anwendungsproblem Dokumentation wie jedes andere Projekt für die Fachseite anzugehen. Zunächst werden die Anforderungen festgelegt, das heißt, welche Handbücher in welcher Gliederung zu erstellen und welche Phasenergebnisse zu dokumentieren sind. Da das Ganze "projektbegleitend" geschehen soll, müssen wir uns auch noch darüber klarwerden, wann die ver schiedenen Kapitel (oder Testbausteine) angelegt und gefüllt werden, um sie später - möglichst automatisch als Stückliste - zu Dokumentationsergebnissen zusammenfassen zu können.

Wir benötigen also ein "ergebnisorientiertes" Systementwicklungskonzept (auch Phasenkonzept genannt) als Organisationsgrundlage für eine vernünftige Dokumentation.

Doch damit nicht genug. Dokumentation ist auch in hohem Maße davon abhängig, welche Methoden wir in den einzelnen Phasen der Systementwicklung einsetzen. "Hipo" verlangt andere Ergebnisse als strukturierte Systemanalyse und strukturiertes Design oder die hausgemachte Verfahrensweise. Hinzu kommt, daß alle projektbegleitend entstehenden Teilergebnisse hochgradig miteinander verknüpft sind (Funktionen, Programme, Datenelemente, Jobs).

Ein Editor, ein normales Textverarbeitungssystem oder ein Textformatierer reichen zur Unterstützung der Dokumentationsarbeit nicht aus. Es muß vielmehr ein dediziertes Werkzeug mit folgenden Schwerpunkten sein:

- Unterstützung von Netzstrukturen

Daten und Prozesse müssen in ihrer funktionalen und DV-technischen Ausprägung, unterschiedlichen Detaillierungsebenen und ihren Beziehungen und Verwendungen zueinander dokumentiert werden. Der automatische Aufbau und die Verwaltung dieser Beziehungen verlangt ein System zur Unterstützung von Netzstrukturen. Da es kein verbindliches Dokumentationsmodell gibt, muß die Struktur vom Benutzer frei definierbar sein.

- Fertige Auswertfunktionen

Dazu gehören Verwendungsnachweise, Struktur-Darstellungen, Schnittstellenanalysen, Entwurfshilfen, Unterstützung der Erstellung fertiger Handbücher.

- Ad-hoc-Auswertungen und Unterstützung von Schlagwortverzeichnissen

- Dialogsystem

Das System muß einfach und ohne großen Lernaufwand bedienbar sein - für den gelegentlichen Benutzer (beispielsweise Fachseite) wie für den Experten.

- Kundenindividuelle Gestaltung der Benutzeroberfläche

Die Akzeptanz hängt wesentlich davon ab, daß die Funktionalität des Systems kundenindividuell erweitert werden kann. Geeignetes Mittel dafür ist Prozedurfähigkeit.

Dokumentation in den Griff zu bekommen, heißt also, die Systementwicklung insgesamt in den Griff zu bekommen. Und da schadet es nichts die eigenen Erfahrungen durch die Erfahrungen anderer anzureichern, die diese Aufgabe inzwischen mit einem deutlichen Schritt nach vorn bewilligt haben.