***

Wie schreibt man eine Projekt-Dokumentation?

Hinweise zur richtigen Dokumentation von Programmsystemen

Verfasser: Otto Praxl

Inhalt

Vorwort
Literatur
Projektdokumentation
Programmdokumentation
Der fachkundige Dritte
Verschleierungstaktik
Schlusswort

Vorwort

Wenn den Studenten der Informatik gesagt wird, dass die von ihnen erstellte Software gut dokumentiert werden muss, dann glauben sie es so lange nicht, bis sie ein von ihnen selbst erstelltes und nicht ausreichend dokumentiertes Programm nach einiger Zeit selbst ändern müssen. Professoren beweisen dies, indem sie den Studenten ein zu Beginn des Semesters erstelltes Programm am Ende des Semesters ändern lassen.

Der Grund für das Scheitern großer Projekte ist meist eine schlechte Dokumentation. So hatte eine Firma für eine Behörde ein 400.000 Euro teures Programmsystem erstellt und musste es aufgrund von später hinzugekommenen Erweiterungen laufend ändern. Der ursprüngliche Programmierer war nicht mehr greifbar, sein Nachfolger musste sich mühsam in dem schlecht dokumentierten Programm zurechtfinden. Er gab auf und seinem Nachfolger erging es auch nicht anders. Nach 3 Jahren musste die Firma eingestehen, dass das Programm nicht mehr pflegbar war. Die Behörde bestellte ein neues Programmsystem bei einer anderen Firma und schrieb nun genau vor, wie die Dokumentation aussehen muss, um nicht wieder einen Reinfall zu erleben.

In folgenden Beitrag wird kurz gezeigt, worauf es bei der Dokumentation ankommt.

Literatur

[1] Das Buch "Softwaretechnologie" von Prof. Dr. Franz Stetter (1981, Reihe Informatik, Band 33, ISBN 3-411-01617-5, BI-Wissenschaftsverlag) ist eine Einführung und widmet ein ganzes Kapitel der Dokumentation.

[2] Das Buch "Die Entwicklung von Software-Systemen" von Prof. Dr.-Ing. habil. Helmut Balzert (1992, Reihe Informatik, Band 34, ISBN 3-411-01618-3, BI-Wissenschaftsverlag) beschreibt Prinzipien, Methoden, Sprachen, Werkzeuge und die einzelnen Phasen einer Software-Erstellung sehr detailliert.

Projektdokumentation

Ein Kernsatz in [2] lautet:
Ein Software-Produkt ist nur so gut wie seine Dokumentation.

Inhalt der Dokumentation, grafisch
          dargestellt

Die Projektdokumentation muss alle Einzeldokumentationen zusammenfassen. Die Projektdokumentation eines Software-Systems muss alle Akten eines Projekts enthalten. Dazu gehören alle Unterlagen, die bei der Planung, der Erstellung, der Installation und dem Betrieb des Systems entstanden sind und noch laufend entstehen. Also auch Entscheidungsprotokolle, Schriftverkehr, Pläne, Besprechungsprotokolle, Handbücher, Betriebstagebuch und vieles andere mehr.

Wichtig ist vor allem die projektbegleitende Dokumentation, weil hinterher sonst keiner mehr weiß, warum welche Entscheidung gerade so und nicht anders getroffen worden ist.

Auch die nachfolgend vereinfacht dargestellte Programmdokumentation ist ein wichtiger Bestandteil der Projektdokumentation.

Programmdokumentation

Die Programmdokumentation besteht meist aus vier mehr oder weniger klar abgegrenzten Teilen:

  1. Dokumentation der Problemlösung (Problembeschreibung und Lösung)
  2. Dokumentation des Programmes (Programmbeschreibung, Quellcode)
  3. Dokumentation der Installation (Installationshandbuch)
  4. Anleitung für den Anwender (Anwenderhandbuch).

Problembeschreibung und Lösung

Jeder Anwender eines anspruchsvollen Programmes sollte wissen, wie das von ihm benutzte Programm das gestellte Problem löst. Er muss wissen, ob das Programm für die Lösung seines Problems anwendbar ist. Deshalb sollte er fragen:

Was tut das Programm?
Wie löst es das Problem?

Sofern das Programm gut dokumentiert ist, findet er die Antworten in der Problembeschreibung. Dort stehen Zusammenhänge, Hintergründe, Formeln, Bezeichnungen, Definitionen und alles, was als Randbedingung zu berücksichtigen war. Dann kann der Anwender entscheiden, ob das Programm für sein Problem brauchbar ist.

Programmbeschreibung

In der Programmbeschreibung erfährt der Anwender detailliert, wie die Problemlösung im Programm realisiert wurde. Dort sind die Variablennamen und deren Bedeutung aufgelistet, dort stehen Kommentierungen an den Stellen, wo Besonderheiten und Zusammenhänge zu berücksichtigen waren und dort sind auch Strukturen gekennzeichnet, wo z. B. Schleifen anfangen und aufhören.

Installationshandbuch

Im Installationshandbuch findet der Anwender alles, was er wissen muss, um das Programm vom Datenträger oder vom Netz auf seinen Rechner zu bringen und es betriebsfertig und lauffähig zu installieren. Informationen über die Systemanforderungen der dazu benötigten Hardware gehören genauso dazu wie eine ausführliche Schritt-für-Schritt-Anleitung zum richtigen Vorgehen beim Installationsvorgang.

Anwenderhandbuch

Das Anwenderhandbuch sollte bezüglich der Handhabung des Programms keine Fragen offen lassen. Hier steht ausdrücklich "Handhabung" und nicht "Bedienung". Ein Programm wird nicht bedient, sondern hat dem Anwender zu dienen, sein Problem zu lösen. Und das Handbuch muss ihm zeigen, was er tun muss, um das Programm zu veranlassen, die Lösung zu liefern.

Grundsätzlich sollten mindestens folgende Themen im Anwenderhandbuch erschöpfend beschrieben sein:

Starten des Programms
Einstellung wichtiger Parameter der Hardware (z.B. Flags, nötige Treiber)
Einstellung der richtigen Formate und Modi (z. B. Winkel in Radiant oder Grad)
Format der Eingabedaten
Anzeigeformat für die Ausgabe der Ergebnisse (Stellenzahl der Werte)
Datenträgerverwendung
Datenverbindungen in Netzwerken
Beenden des Programms (Wie komme ich wieder geordnet raus, ohne das Programm "abwürgen" zu müssen?)

Programmdokumentation bei Standardsoftware

Bei Standardsoftware, also den Programmen, die es fertig zu kaufen gibt, sind meist alle vier Teile (ohne Quellcode) einer Programmdokumentation in einem einzigen Handbuch (Manual) zusammengefasst. Ob das Handbuch dann gedruckt auf Papier oder auf einem Datenträger zum Selbstausdrucken mitgeliefert wird, ist nicht von Bedeutung. Hauptsache ist eine saubere und ausreichende Beschreibung aller wichtigen Einzelheiten und Zusammenhänge.

Der fachkundige Dritte

Diese anonyme Person steht meist in den Ausschreibungen für Software-Systeme. Für die Dokumentation ist dort dann folgender Satz zu lesen:

Die Dokumentation des Systems muss so erstellt werden, dass ein fachkundiger Dritter dadurch in die Lage versetzt wird, das System ordnungsgemäß zu betreiben, zu pflegen und zu ändern.

Die Absicht dieses Satzes ist, einen gewünschten Idealzustand einer Dokumentation allgemein zu beschreiben. Wenn Wunsch und Idealzustand von beiden Vertragsparteien im gleichen Sinn verstanden werden, dann sind keine Schwierigkeiten zu befürchten.

Aber die Praxis sieht anders aus: Diese pauschale Beschreibung wimmelt nur so von unbestimmten Rechtsbegriffen, die später meist dem "Verwender", also demjenigen, der diesen schlauen Satz geschrieben hat, zum Nachteil gereichen. Auch in den Vertragsunterlagen im eingangs erwähnten Fall stand dieser Satz. Der Auftraggeber verlor den Rechtsstreit.

Der "Erste", der "Zweite" und der "fachkundige Dritte"

Der "Erste" ist der Auftraggeber, der Besteller. Er muss nicht unbedingt fachkundig sein, muss sich aber schulen lassen, um später die fertige Software bestimmungsgemäß einsetzen zu können.

Der "Zweite" muss unbedingt fachkundig sein und sein Handwerk verstehen. Es ist der Programm(h)ersteller.

Der sagenhafte "fachkundige Dritte" ist laut obigem Satz als Feuerwehrmann vorgesehen und muss mit seinen fast hellseherischen Fähigkeiten die Fehler und Versäumnisse des "Ersten" und "Zweiten" ausbügeln und aufgrund der Dokumentation erkennen, wie er den Karren wieder aus dem Graben ziehen kann.
Wenn man einen "fachkundigen Dritten" wirklich braucht, dann ist dies der untrügliche Beweis dafür, dass der "Erste" und der "Zweite" zusammen unfähig waren.

Warnung: Die Rolle eines "fachkundigen Dritten" ist die undankbarste Aufgabe, die man sich denken kann.

Verschleierungstaktik

Wenn bei einer Software-Erstellung der Quellcode mitgeliefert werden muss, verschleiern manche Programmierer in der Dokumentation absichtlich den wahren Sachverhalt, um das Programm zur angeblichen Wahrung der Betriebsgeheimnisse schwer oder gar nicht lesbar zu machen. Die Konkurrenz soll es möglichst schwer haben, falls sie das Programm später pflegen muss. Anstelle von "sprechenden Variablennamen" werden dann nichtssagende Bezeichnungen in die Dokumentation geschrieben.

Schwierigere Formeln werden meist in viele Teilausdrücke und Hilfsvariablen zerlegt und sind dann nicht mehr so leicht zu durchschauen. Wie der Autor überrascht festgestellt hat, gibt es auch Programmierer, die tatsächlich so programmieren und es nicht anders kennen und können. Denen ist es dann schleierhaft, dass es auch einfacher gegangen wäre.

Um diese Verschleierungstaktik zu vermeiden, sollte der Auftraggeber nicht nur den Quellcode, sondern auch die Problembeschreibung und den Lösungsansatz mit allen Formeln (in mathematischer Schreibweise) in der Dokumentation verlangen. Schließlich bezahlt er ja bei einem Erstellungsauftrag dafür.

Schlusswort

Die obigen Ausführungen sollen dazu anregen, dass Dokumentationen ganz allgemein verständlicher geschrieben werden. Der Absolvent einer entsprechenden Fachrichtung, sei er nun Mathematiker, Ingenieur, Informatiker, Physiker oder Chemiker, muss als Ersteller von Systemen zugleich technischer Autor sein, der eine Dokumentation ordnungsgemäß zu erstellen in der Lage ist. Er muss voraussehen, was der Leser über das neue System wissen will und wissen muss. Er darf nicht zu große Kenntnisse beim Leser voraussetzen, sondern muss alles erläutern, was zum Verständnis der Dokumentation wichtig ist.

Beispiele für eine ausreichende Programmdokumentation findet der Leser in den PDF-Dokumenten auf dieser Homepage.


© 2017 Otto Praxl. Alle Rechte vorbehalten (Erstveröffentlichung dieses Beitrags am 01.12.2005 auf der Praxelius-Homepage).

Zur Startseite