Ausarbeitung

Die Ausarbeitung ist zu erstellen in HTML. Die HTML-Dateien sind so in einem Verzeichnis anzulegen, daß sie durch einfaches Kopieren dieses Verzeichnisses in ein Archiv übernommen werden können. Das heißt: nur relative Links verwenden; alle Bilder, Icons etc. müssen in diesem Verzeichnis liegen. Über das Erstellen von HTML-Dokumenten informiert ein on-line Manual, das selbst so aufgebaut ist, wie wir es für die Ausarbeitung wünschen. Sie können es sich deshalb auch zum off-line Lesen zu Hause herunterladen.

Die Ausarbeitung umfaßt:

1. Benutzerdokumentation
2. Entwicklerdokumentation
3. die Quell-Dateien mit aussagefähigen Kommentaren
4. das Makefile oder ersatzweise die Anleitung zum Erzeugen des ausführbaren Programms aus den Quellen
5. Testbeispiele

Benutzer-Dokumentation

Die Benutzerdokumentation erklärt die realisierte Funktion und beschreibt, wie das erstellte Programm, das i.a. als Unterprogramm realisiert ist verwendet wird. Hier soll der Benutzer Information zu folgenden Punkten finden:

• Was tut das (Unter)Programm?
  Name und Kurzbeschreibung der Funktion, entsprechend dem Abschnitt NAME in den UNIX on-line Manuals

• Wie ruft man es auf?
  Aufrufsyntax entsprechend dem Abschnitt SYNOPSIS der UNIX on-line Manuals

• Detailliertere Beschreibung des Unterprogramms. Erläuterung der Parameter, erlaubter Wertebereiche, des Verhaltens im Fehlerfall, Fehlercodes, etc.

• Anwendungsbeispiel. I.a. können Sie hier auf Ihre Testumgebung verweisen.

Aus einer gut strukturierten ausführlichen Spezifikation läßt sich vieles in die Benutzerdokumentation übernehmen.

Entwicklerdokumentation

Die Entwicklerdokumentation richtet sich an Programmierer, die z.B. eine neue Option in Ihr (Unter)programm einbauen wollen. Sie soll zusammen mit dem kommentierten Quellcode Lösungsansatz und Realisierungskonzept verständlich machen. Sie soll Auskuft geben zu folgenden Punkten:

• Wie wird die Aufgabe gelöst?
  Der realisierte Lösungsansatz wird beschrieben

• Warum gerade so?
  Der gewählte Ansatz wird begründet. Dazu gehört auch alternative Lösungsmöglichkeiten aufzuzählen und die Abwägung zu dokumentieren, die zu der Auswahl geführt hat.

• Was ist zu tun, um eine etwa eine neue Option zu integrieren?
  Natürlich kann und soll man nicht alle erdenklichen Erweiterungen hier berücksichtigen; zu den einigermaßen naheliegenden sollte aber was gesagt werden.
  Im schon mehrfach bemühten Beispiel der Heizungssteuerung sollte man etwa darauf eingehen, was am Steuerprogramm zu tun ist, wenn ein weiterer Temperatur-Sensor angeschlossen werden soll.

Eine gut gemachte Spezifikation liefert auch viele Teile der Entwicklerdokumentation. Diese Dokumentation soll vor allem die Verbindung zwischen der Spezifiaktion des Lösungswegs und seiner Implementierung in Assemblersprache deutlich machen.