Praktisches & Grundsätzliches zur Informatik

Software Dokumentation: Gestaltungsform, Specification Cards, Project Web Format

Wie Software-Dokumentation gestalten?

Leider wird auch heute noch sämtliche Dokumentation, die vor allem Entwickler und Tester lesen sollten, von ihnen nur allzu selten auch wirklich in ausreichenden Maße genutzt (insbesondere Tester — soweit nicht identisch mit den Entwicklern — kennen solche Dokumentation kaum (selbst dann nicht, wenn sie wirklich existiert). Ihre Arbeit wird weniger effektiv sein, insbesondere was Test betrifft.

Diese traurige Tatsache hat vor allem zwei Gründe:

Allein schon diese kurze Analyse macht klar, was notwendig ist, die Situation zu verbessern:

Die sog. Software-Krise gegen Ende der 60-er Jahre hat klar gezeigt, welch wichtige Rolle Konzept­dokumentation in der Welt der Software hat, ist es noch weitere 30 Jahre (eben bis hin zur Erfindung von HTML) nicht gelungen, sie so zu gestalten, dass während der Erstellung von Anforderungs- und Design­papieren Gelerntes nach der Fertigstellung solcher Dokumente nicht schnell wieder in Vergessenheit gerät. Wer sich jemals gezielt mit dieser Problematik auseinandergesetzt hat, dem ist heute klar: Solche Dokumentation richtig zu nutzen, gelingt nur dann, wenn die Personen, für die sie eigentlich geschrieben wurde (Programmierer und Tester) von sich aus nach ihr greifen.

Hierzu aber muss sie — dokumentenübergreifend

sein. Ich kenne nur einen Weg, über den man dies wirklich erreicht:


Specification Cards — typisierte Identifier — Projectwebs


Projectweb — das projekteigene Dokumentationsnetz mit Index

Software-Dokumentation entsteht als Folge von Dokumenten, die in aller Regel von Hand per MS Office editiert werden. Nicht selten existieren zeitgleich mehrere Versionen je eines solchen Dokuments. Aus Sicht der Leser, die nicht auch Autor dieses Dokuments sind, interessiert stets nur eine einzige davon (welche genau, muss in einer das Projectweb definierenden Konfigurationsdatei festgehalten sein).

Wird einem geeigneten Werkzeug (z.B. meinem docs2web.exe diese Konfigurationsdatei genannt, so kann es mit ihrer Hilfe die Menge aller darin genannten Dokumente — in der jeweils richtigen Version —

Betrachten wir als Beispiel fünf in dieser Weise zusammengefügte Dokumente aus Project WissDB (statt nur 5 Dokumente könnte man auch 55 oder noch mehr haben – die Zahl spielt, was das Erzeugen so eines Webs betrifft, keine Rolle).

Wer das Beispiel aufblättert erkennt:

Damit kann der Leser nach Begriffen ebenso leicht suchen wie nach Dokumenten. Mehr noch: Im Index ist jeder Begriff mit Kontext aufgelistet (so dass der Leser sofort sehen kann, welche Stellen ihn interessie­ren oder eben jetzt nicht interessieren könnte; siehe z.B. den Begriff C_WissDB_API. Ob gesuchte Information vorhanden ist, lässt sich so recht schnell erkennen — ist sie nicht vorhanden, kann sie jetzt gezielt ergänzt werden. Damit hilft die Indizierung auch den Autoren der Dokumente, genauer: dem Autor der jeweils nächsten Version.

Beides zusammen garantiert, dass dem Leser tagesgenau alle relevante Dokumentation in genau richtiger Version stets zur Verfügung steht. Mühsam nach den richtigen Dateien zu suchen — nur um so vielleicht die falsche als die richtige anzusehen — ist so nicht mehr notwendig. Prinzip also:

Sämtliche vorhandene Dokumentation komme selbst zum Leser
dies verkleinert die Hürde, dort auch wirklich nachzuschlagen.


Typisierte Identifier — automatischer Verlinkbarkeit wegen

Die Autoren der Dokumente sollten darauf achten, dass schon die Überschrift jeder Specification Card — allgemeiner: die Überschrift jedes Abschnitts im Dokument — einen typisierten Identifier enthält. Man versteht darunter einen Namen für das vor allem in diesem Abschnitt beschrienene Konzept, dem ein das Konzept typisierender Buchstabe gefolgt von einem Underscore vorangestellt ist. Solche Buchstaben sollte es nur wenige geben, z.B. nur die folgenden (siehe hinter jedem Link ein Beispiel):

Wo kein anderer Typ besser passt, verwende man den per definitionem immer passenden Typ C_ (jedes Schema sollte wenigsten ihn enthalten).

Für die Indizierung wichtig ist: In dieser Überschrift — und wirklich nur hier — darf und muss zwischen Typsilbe und Name ein Space stehen; er kennzeichnet diese Seite als jene, auf der Begriff eingeführt wird. Er kann dann aber quer über alle Dokumente hinweg benutzt werden und wird dort automatisch mit einem Hyperlink auf die ihn definierende Seite versehen.

Nützlicher Nebeneffekt dieser Konvention: Beim Generieren des Projectwebs kann so automatisch eine Seite entstehen, die alle benutzten aber noch nicht definierten Begriffe zeigt. Sie ist erreichbar über den Link UNDEFs, der mindestens in der Kopfzeile der Eingangsseite zum Index auftritt.

Es war für mich stets erstaunlich zu sehen, in welch hohem Maß eben dieses Feature dazu beiträgt, Dokumentation gezielt und in kürzester Zeit zu erstellen (dann jedenfalls, wenn man sich diesen auf Lücken und Inkonsistenzen hinweisenden UNDEFs Report oft genug ansieht (am besten jeden Tag als jemand, der Entwurfsdokumente zu pflegen oder fertigzustellen hat).

Nicht zuletzt weisen in der Dokumentation — z.B. hier — gefundene, automatisch eingesetzte Fragezeichen [?] alle Leser, Prüfer und Autoren klar darauf hin, zu welchen Begriffen eine eigentlich notwendige Spezifikation derzeit noch fehlt.

Da alle nach der Regel oben typisierten Identifier mit Links zur sie definierenden Seite hinterlegt sind, gelangt man als Leser per Mouse Click sofort dorthin — ganz unabhängig davon, in welchem der Doku­mente sie sich findet.

Dass diese Darstellung aller Texte in HTML aus normalen Textverarbeitungsformaten (DOC, RTF, TXT, heute aber am besten *.ODT) automatisch erzeugbar sein kann und muss, versteht sich von selbst:

Nach jeder Freigabe eines neuen Dokuments durch den Quality Manager sollte er die das Project Web definierende Stückliste aktualisieren und den Dienst aufrufen, der das gesamte Project Web neu erzeugt. Es ist dann dann auch garantiert, dass niemand mehr eine schon überholte — oder eine noch nicht freigegebene — Version der einzelnen Spezifikationen nutzt und jeder im Team stets genauestens darüber informiert ist, welche Dokumentation denn eigentlich existiert. Dies erreicht zu haben, sollte nicht unterschätzt werden: Ich habe Projekte erlebt, in denen noch nicht mal die Tester genau wussten, wo sich denn nun eigentlich die Spezifikationen fanden, gegen deren Vorgaben sie das entstandene Produkt hätten testen müssen.



Specification Cards — die Dokumentationsatome

Dass sämtliche Dokumentation potentiellen Lesern heute in HTML präsentierbar sein sollte, wurde schon gesagt: Nur so nämlich wird sie auch wirklich genutzt.

Der Notwendigkeit wegen, Konzepte fortzuschreiben zu können, wenn neue Erkenntnisse gewonnen werden oder die Software selbst sich ändert, dürfen solche Papiere auf keinen Fall aufsatzartig geschrieben sein. Diese Erkenntnis wird allzu oft ignoriert – passt aber gut zur Anforderung, sämtliche Dokumentation wie einen Webauftritt zu präsentieren: extrem modular und so, dass der Inhalt jeder Seite weitgehend in sich abge­schlossen ist und man somit nicht gezwungen ist, sie in irgend einer festen Reihenfolge zu lesen. Es kann dann jede Seite als eine Art gedanklicher Tasse betrachtet werden, in der man Wissen aufbewahrt. Einzel­ne Tassen zu streichen oder neue zu erzeugen ist einfach (Aufsätze abzuändern ist deutlich schwieriger und mit sehr viel mehr Aufwand verbunden). Dokumentation wird damit
vom Roman zum Lexikon


Wie aber lässt sich dieser Weg nun konkret gehen?

Schlüssel dazu sind formularartig gestaltete Seiten (sog. Specification Cards), die sich in HTML auto­matisch miteinander verlinken lassen. Hier zwei typische Beispiele: [1], [2].

Sie entstehen, indem man Wissen über das System im top-down-Vorgehen sammelt und aufschreibt (Ent­wickler müssen es ja ohnehin in auf diesem Weg erarbeiten, können es dann also auch sofort so auf­schrei­ben).

Zu diesem Zweck nimmt man sich vor, jeden Teil des Systems — zunächst also das ganze System — auf nur etwa einer Seite kurz zu charakterisieren. Mit Teil dieser Seite ist eine Liste der Teile, in die der jeweils beschriebene Gegenstand — das System, ein Subsystem, eine seiner Komponenten, ein Komponenten­schnittstelle oder ein anderes wichtiges Konzept — sich direkt zerlegt. Ausgehend von dieser Liste kann dann auch zu jedem dieser Teile einzeln und nach demselben Verfahren eine eigene Specification Card angelegt werden.

Eine Sammlung bewährter Templates hierfür findet man z.B. in [3]. Man kann die Karten aber letztlich gestalten, wie man will (denn einzige Voraussetzung ist, dass darin — möglichst schon in einer ihrer ersten Zeilen — der das beschriebene Konzept benennende typisierte Identifier auf­tritt).

Natürlich kann in Specification Cards auch Graphik auftreten (z.B. ein Architekturbild, ein Inter­aktions­diagramm, Screeshots oder eine in UML notierte Illustration des Zusammenwirkens wichtiger Klassen im Code).

WARNUNG: Software vorwiegend in UML beschreiben zu wollen, ist ein aussichtsloses Unterfangen und führt stets zu absolut unbrauchbarer Dokumentation (auch wenn Theoretiker an Hochschulen das anders sehen). UML Diagramme können nur Salz in der Suppe sein – niemals aber die Suppe selbst.

Meine Faustregel: Per UML hilfreich dokumentiert sein kann nur ein Programm, welches nicht wesentlich mehr als etwa 1000 LOC enthält.
Wissenswertes zu "Project Web Format, Specification Cards, Software Dokumentation: Gestaltungsform" zusammengestellt durch Gebhard Greiter.
tags: Dokumentation1gegreit Specification1gegreit Leser1gegreit