Dokumentation von Softwareprojekten

[Michael Schröpl]

Hi Martin,

Demnächst steht für ein von meiner Firma program-
miertes Softwareprojekt eine Dokumentation an.

bist Du Dir bewußt, welche Zielgruppe(n) welche Fragen
an diese Dokumentation haben werden?

Jetzt wollte ich fragen, wie "Profis" so etwas
anfassen. Mir scheint es momentan so zu sein, dass
jeder sein eigenes Süppchen braut und je nach Gusto
Word, PDF-Writer, HTML etc. nutzt.

Ich halte das verwendete Format für sekundär - so etwas
zu konvertieren kann im Zweifelsfalle ein Programm tun.

Die Inhalte der Dokumente (Plural ist Absicht) sind
weitaus wichtiger.

Wir benötigen

Das ist der Punkt, der mich am meisten interessiert.

Punkt 1: Wo ist die Spezifikation, das allerwichtigste
Dokument überhaupt?

• Inhalt:     _Was_ kann das Produkt? (nicht _wie_)
• Zielgruppe: Management, Vertrieb, Kunden (nicht User!)

• Benutzerhandbuch (Extern)

Inwiefern ist dies identisch mit der in das Produkt
eingebauten Online-Hilfe? Läßt sich vielleicht sogar
beides aus demselben Quelltext generieren?

• Administrationshandbuch (Intern. enthält z.B.
  Coding-Rules, etc.)

Beides würde ich nicht in dasselbe Dokument stecken.

Ein Administrationshandbuch sollte zur Administration,
also Bedienung des Produkts dienen.
Da sollten also alle vorhandenen Einstellungsmöglich-
keiten detailliert beschrieben werden - in einem Maße,
das für den Leser des Benutzerhandbuchs zu detailliert
oder uninteressant sein darf. Ein RZ-Mitarbeiter sollte
die Antwort auf alle seine Fragen hier finden. Auch
allgemeine Dinge wie Betriebskonzept, Backup-Konzept
usw. gehören also hier hinein.
Zielgruppe sind Administratoren, Operateure etc.; auch
ein sehr engagierter Anwender sollte das lesen können.

Die Programmdokumentation ist dagegen ein Dokument,
das sich ausschließlich an Programmierer wendet.
Hier stehen sowohl Coding-Rules (m. E. weniger wichtig)
als auch der grundsätzliche Aufbau des Programms, ins-
besondere die Modul-Struktur und die APIs der wichtig-
sten Funktionen. Ebenso sind hier grundsätzliche De-
sign-Entscheidungen dokumentiert - "warum wurde das so
und nicht anders implementiert?". Verworfene Alternati-
ven zu dokumentieren ist sehr wichtig.
Es ist nicht unüblich, diese Informationen direkt im
Quelltext des Programms abzulegen (und ggf. via Tools
daraus zu extrahieren, um separate Dokumente daraus zu
erzeugen). Denn wer dieses Dokument lesen kann, der hat
auch mit dem Quelltext zu tun und wird sich freuen,
wenn die Information dort steht, wo er sie braucht
(und ggf. via "grep" etc. finden kann).

Viele Grüße
      Michael