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:

• Der inhaltliche Aspekt:
  
  Insbesondere in Projekten, in denen sich sämtliche Entwickler noch persönlich kennen, wird Konzeptdokumentation (Pflichtenheft, Entwurfspapier und vom Systemarchitekten erstellte Dokumentation) nach dem letzten Review eines solchen Papiers selbst von den Programmieren kaum noch wirklich gelesen.
  
  Die Tatsache nämlich, dass auch diese Papiere ständiger Aktualisierung bedürften — man aber glaubt, dafür weder Zeit noch Geld zu haben — lässt sie schnell an Wert verlieren: als nicht wirklich lesenswert erscheinen. Profitiert haben dann eigentlich nur ihre Autoren, andere Personen aber kennen solches Design nur flüchtig, im Zweifelsfall denken sie sich selbst was Neues aus ...
  
  
• Der präsentationstechnische Aspekt:
  
  Ein zweiter Grund, warum Konzeptdokumentation schlicht und einfach links liegen gelassen wird, ist die Tatsache, dass sie häufig viel zu wenig systematisch verwaltet und überhaupt nicht indiziert wird — man kann verstehen, dass von Terminen getriebene Programmierer dann gar nicht erst zu suchen anfangen (klar: wer sich über irgend einen kleineren, nicht wirklich zentralen Aspekt zu informieren wünscht, kann bei fehlender Indizierung der Dokumentation ja noch nicht mal auf Anhieb erkennen, ob existierende Papiere über den ihn gerade interessierenden Aspekt denn überhaupt etwas aussagen).
  
  

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 —

• einheitlich strukturiert,
• systematisch indiziert,
• per HTML einsehbar
• selektiv lesbar und daher extrem gut modularisiert
  
  

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 —

• auffinden,
• nach Abschnitten (idealerweise nach Specification cards) zerlegen,
• diese indizieren
• und zu einem Webauftritt zusammenstellen.
  
  

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:

• In der ersten Zeile jeder Seite findet sich stets ein Link hin zum Index aller so publizierten Dokumentation.
• Zudem ist da stets ein weiterer, der zur Liste aller publizierten Dokumente führt: DOCs oder Dokumente.
  
  

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.

• Die Konfigurationsdatei zum Projweb (hier die zu unserem Beispiel) sollte am besten durch eine Person gepflegt werden, die im Projekt für Qualitätsmanagement zuständig ist.
• Automatisches Neugenerieren des Webs kann und sollte täglich einmal (in der Nacht etwa) ange­stoßen werden.
  
  

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):

•   R_   für   Requirement
•   A_   für   Actor
•   P_   für   Process
•   C_   für   Component (= Konzept oder Systemkomponente)
•   S_   für   Service (= aufrufbare Funktion einer Systemkomponente)
•   B_   für   Business Object (= Typ oder Datenbestand)
  
  

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.



stw5814DSL — Dokumentation . Specification . Leser — News?

Mehr + B G E + S H A + More

Template for Software Architecture Documentation

arc42 Dcumentation Content
 

07.03.2021
© 2021 Impressum, top