Was kennzeichnet gute Software-Dokumentation?

Moderne Software-Systeme sind — mindestens aus Sicht ihrer Ersteller und Betreiber — äußerst komplexe Gebilde, die zudem noch ständig korrigiert, erweitert oder einer sich ändernden Umgebung angepasst werden müssen.

Software nach Zweck und innerem Aufbau gut verständlich zu halten

• ist demnach wichtig,
• ist erfahrungsgemäß aber schwierig, da Programmierer selten gute Dokumentation abliefern.
  
  

Es lohnt sich somit, darüber nachzudenken, wie Software-Dokumentation nach Umfang, Form und Struktur gestaltet sein muss, um ausreichend nützlich sein zu können, d.h. um die notwendige Fortent­wicklung der Software nicht zu behindern, allzu teuer oder gar unmöglich zu machen.

Notwendiger Umfang akzeptabler Software-Dokumentation

Siehe auch: Was die Rechtsprechung dazu sagt und eine Grundsatzentscheidung.

Wer ein Softwareprodukt entwickeln lässt, sollte darauf achten, dass zusammen mit dem Programm an ihn auch ausgeliefert werden:

• Anforderungsdokumentation
• Anwenderhandbuch
• Betreiberhandbuch
• Architekturbeschreibung (Konzepte, Struktur, Schnittstellen)
• Code-Dokumentation
• Testtreiber
  
  

Auch Testtreiber als Software-Dokumentation zu sehen, erscheint zunächst ungewöhnlich, macht aber Sinn, da nur über sie der Grad an Fehlerfreiheit feststellbar ist. Ihn erkennen zu können, ist wichtig, da über den ganzen Lebenszyklus der Software hinweg zu starkes Absinken ihrer Fehlerfreiheit möglichst umgehend erkennbar sein muss.

Insgesamt gilt:

• Testtreiber sind ebenfalls Software und werden am besten ins Produkt selbst integriert, so dass es stets möglich ist, den gesamten Test neu aufzurufen und so ein Aufruf insbesondere auch Teil des Build-Prozesses sein kann (also stets erfolgt, wenn die Software fortgeschrieben wird: man spricht hier von Regressionstest). Zudem muss dieser Test – damit er erweiterbar und selbst flexibel neuen Gegebenheiten anpassbar ist – tabellengetrieben arbeiten: Man muss die Gesamtheit dieser Tabellen als einen seiner Aufrufparameter realisiert sehen. Das gesamte Testergebnis sollte sich dem Aufrufer mindestens in HTML präsentieren, und sämtliche durch das System als Black Box im Zuge eines Testlaufs errechneten Daten sollten sich – als Test Trace – in TXT dargestellt vorfinden (nur dann nämlich können Betreiber oder Anwender später eigene, zusätzliche Prüfungen vorzunehmen).
• Code-Dokumentation ist der Teil an Dokumentation, den Entwickler noch am ehesten liefern: Sie entsteht als Kommentar im Code und kann – wie z.B. bei Java-Anwendungen heute allgemein üblich – automatisch aus dem Code extrahiert und dem Leser in HTML präsentiert werden (hier ein ganz typisches Beispiel: Es zeigt eindrucksvoll, dass Code-Dokumentation i.A. nicht dafür geeignet ist, die Implementierung eines Systems schnell zu verstehen — dazu sollte man Architektur- und andere Konzept­dokumentation haben; die nämlich erklärt auch übergeordnete Zusammenhänge und ist – da nicht an Code gebunden – sehr viel schneller verstehbar).
• Anforderungsdokumentation hat alle – und nur – Eigenschaften des Systems zu beschreiben, die aus Sicht der Anwender und Nutzer explizit gewünscht sind (der Entwickler ist frei nur in der Gestaltung aller hier NICHT beschriebenen Eigenschaften).
  
  Anforderungen systematisch zu verwalten gelingt sehr gut mit TestLink.
• Alle Handbücher – auch die Architekturdokumentation – sollten im DOC Format vorliegen um so der der Tatsache Rechnung zu tragen, dass sie später jeder Änderung der Software entsprechend fort­schreibbar sein müssen. Wo nämlich Software sich weiterentwickelt ohne dass die Handbücher und Testtreiber hierzu synchron mit aktualisiert werden, ist Systemdokumentation in kürzester Zeit absolut wertlos. Sobald das passiert, sind sämtliche Wartungsarbeiten mit höherem Risiko verbunden und zudem nur mit deutlich höherem Zeitaufwand möglich. Die Abhängigkeit des Unter­nehmens von der Verfügbarkeit wichtiger Knowhow-Träger wird unangemessen groß.
• Durch den Hersteller der Software nur in PDF abgelieferte Dokumentation verliert ihren Wert, sobald die Software korrigiert oder irgendwie sonst fortgeschrieben werden muss.
  
  Dokumentation nur in PDF zu erhalten ist daher auf keinen Fall akzeptabel (nicht für den jeden­falls, der solche Software dann selbst zu pflegen hat oder frei sein möchte, andere Personen als die ursprünglichen Entwickler damit beauftragen zu können). Siehe auch:
  
  Konzeptdokumentation — Techniken, sie möglichst wertvoll zu machen
  
  

stw6175DTE — Dokumentation . Testtreiber . Entwickler — News?

Mehr + B G E + S H A + More

Notwendige Dokumentation

Basiswissen zu Software-Dokumentation