The Weapon of Choice der Softwaredokumentation

Softwaredokumentation – ein leidliches Thema

Wer will schon ein hunderte Seiten langes Dokument schreiben, welches eh niemand ließt. Informationen über die Entwicklung der Software müssen genau dann vorliegen wenn sie gebraucht werden. Also während der Planung beziehungsweise bevor ein Feature implementiert wurde. Danach entweder nie mehr oder wenn es akut ist. Zum Beispiel wenn ein Fehler aufgetreten ist. Da macht es nachvollziehbar wenig Spaß unter Termindruck auch noch lange Softwaredokumentation zu schreiben oder in der Dokumentation zu suchen nach bestimmten Lösungen zu suchen.

Wikis können hier eine praktische Lösung sein. Denn Dokumente können nebenbei von Überall bearbeitet werden und zusätzlich lassen sie sich durchsuchen.

Meine Vorliebe liegt hier bei Confluence. Xwiki als Alternative fand ich auch sehr gut.

Aber wie mit einer blanken Wiki Software dokumentieren?

Softwareprojekt-Space

Um ein Softwareprojekt zu dokumentieren gehe ich in Confluence folgendermaßen vor:

Space anlegen

Im Hauptmenü unter Spaces (Bereiche) kann ein neuer Space angelegt werden, den Sie für die Dokumentation Ihrer Software nutzen können. Ich würde für jedes Projekt einen eigenen Space anlegen.

Klicken Sie auf Create space (Bereich anlegen). Wählen Sie dort den Projekttyp Software project space aus. Im darauf folgenden Dialog können Sie unter Project ein JIRA-Projekt auswählen. Name, Projektschlüssel und Beschreibung können Sie darauf hin anpassen/eintragen.

Confluence legt jetzt einen Space an und fügt direkt einige praktische Seiten hinzu. Mit diesen Seiten können Sie direkt mit dem schreiben Ihrer Dokumentation beginnen.

Auf der Startseite sehen Sie eine Todo-Liste mit Aufgaben, die Sie abarbeiten sollten. Klicken Sie dazu auf Edit (Bearbeiten) um in den Editor zu wechseln.

Ich möchte an dieser Stelle auf die Beschreibung der Benutzung des Editors verzichten. Confluence bietet hier selbst eine gute Anleitung an.

Bereiche im Space

Interessant sind allerdings die neuen Bereiche die Sie in der Sitebar finden. Hier finden Sie die Punkte:

• Decision log (Entscheidungsprotokoll)
• File lists (Dateilisten)
• Meeting notes (Besprechungsnotizen)
• Product requirements (Produktanforderungen)
• Retrospectives (Rückblick)

Jeder dieser Seiten stellt eine Top-Seite dar unter denen Seiten vom entsprechenden Typ gesammelt werden.

Entscheidungsprotokolle dokumentieren eine Entscheidungsprozess, der beim Bestimmen von Produktanforderungen helfen soll.

Produktanforderungen fassen neue Feature, Kundenwünsche, Anforderungen wie bessere Usability oder klareres Design für einen bestimmten Entwicklungsschritt zusammen. Sei es eine Iteration (Sprint) oder die nächste Version der Software.

Rückblicke dienen zur Betrachtung eines Entwicklungsschritts nach der Implementierung und dem Deployment. Hier kann nochmal festgehalten werden was gut gelaufen ist oder wo es Probleme gab. So ist es möglich bewusst aus Fehlern führ die Zukunft zu lernen.

Wenn Sie einer der Top-Seiten aufrufen werden Sie feststellen, dass sich auf jeder der Seiten ein Button befindet. Über diese gelangen Sie auf die entsprechende Unterseite. Da dem Projekttyp noch eine Möglichkeit fehlt die eigentliche Planung und Entwicklung an sich festzuhalten wäre es schön wenn man solch ein Feature auch für weitere Seiten anbieten könnte. Mit eigenen Templates ist dies möglich.

Globale Templates anlegen

Um globale Templates anlegen zu können müssen Sie Administrator sein. Es bietet sich jedoch an die folgenden Templates global anzulegen, da sie so von allen Softwareprojekten genutzt werden können. Um in die Einstellungen zu kommen klicken Sie auf General configuration. In der deutschen Version heißt der Punkt Allgemeine Konfiguration.

Sie werden nun aufgefordert sich als Administrator zu authentifizieren. Klicken sie jetzt im Seitenmenü auf Global Templates and Blueprints (Globale Vorlagen und Blaupausen).

Hier finden Sie einen Button zum Anlegen neuer Vorlagen. (Add global page template/Vorlage für globale Seite hinzufügen). Ein Klick auf diesen Button öffnet den Editor indem der Inhalt der Vorlage bearbeitet werden kann.

Wie oben schon erwähnt wäre ein neuer Bereich praktisch indem die eigentliche Implementation der Software dokumentiert werden kann. Das heißt indem aus den Produktanforderungen tatsächlich eine neues Release der Software wird.

Die Antwort fand ich direkt bei Attlassian. In einem Blogbeitrag beschrieben die Entwickler wie Confluence bei Attlassian eingesetzt wird um eine minimale Softwaredokumentation zu verfassen. Ich habe die Vorgehensweise adaptiert und noch ein wenig erweitert.

Seitenhirachie einer Softwaredokumentation

Eine mögliche Seitenhierarchie könnte folgendermaßen aussehen:

• Decision log (Entscheidungsprotokoll)
• File lists (Dateilisten)
• Meeting notes (Besprechungsnotizen)
• Product requirements (Produktanforderungen)
• Release planning
  • Release v.x.x.x
    • Competitor insights
      • Insight 1
      • Insight 2
      • …
    • Design hub
      • Note 1
      • Note 2
      • …
    • Worknotes
      • Issue 1
      • Issue 2
      • …
    • Testing
      • Testcase 1
      • Testcase 2
      • …
• Retrospectives (Rückblick)

Unterseiten des Release-Planning-Bereichs

Unter einer Seite Release planning werden Bereiche zusammengefasst, in denen die Dokumente eines einzelnen Releases gesammelt werden. Das einzelne Release ist die Umsetzung eines Projektanforderung-Dokuments.

Eventuell gibt es bereits vergleichbare Software oder Konkurenzprojekte. Es lohnt sich also diese zu betrachten um die guten Ideen zu adaptieren und die Schwächen dieser zu vermeiden. Selbstverständlich gilt es hier fair zu bleiben und kein Reverseengeneering zu betreiben. Aber bei Open Source-Software lohnt es sich auf jeden Fall zu schauen, wie Probleme hier gelöst werden. Ergebnisse dieser Recherche können in die eigene Software einfließen und unter Competitor insights gesammelt werden.

Der Design hub umfasst alle Dokumente, die das Design der Software oder der GUI beschreiben. Hier können Infos zu Farbschemas, Mockups, Diagramme aller Art ect. zusammengetragen werden.

Während der Planung entstehen eine Menge Userstories, die in JIRA als Issue angelegt werden. Während der Umsetzung der Issues lege ich für jeden Issue ein Dokument unter Worknotes an um alle anfallenden Notizen, Links oder auftauchende Probleme festhalten zu können.

Unter Testing können letztendlich Testfälle beschrieben werden, die nicht automatisiert werden können. Sprich Integrationstests oder Abnahmetests des Produktivsystems.

Jetzt ist es an der Zeit die einzelnen Templates anzulegen.

Release planning

Klicken Sie auf den Button Add global page template (Vorlage für globale Seite hinzufügen) und legen Sie Ihr erstes Template an. Als erstes muss der Name des Templates angegeben werden. Dieser ist nicht nur die Überschrift sondern tatsächlich der Name unter dem das Template in Confluence gefunden werden kann. Nennen Sie es Release planning. Der Zweck dieses Templates wird es sein eine Top-Seite für die Umsetzung eines Releases anzulegen. Neben dem Button zum Anlegen solch einer Seite brauchen wir eine Übersicht über die angelegten Unterseiten. Mit anderen Worten: Die Seite soll sich genauso verhalten wie die Seite zum Anlegen der Produktanforderungen.

Shortcode

Eine praktische Funktion von Confluence erlaubt es uns nicht mal die Hände von der Tastatur nehmen zu müssen. Tippen Sie { um die Schnellsuche für Macros aufzurufen und geben Sie weiter create from template ein. Groß-/Kleinschreibung spielen hier keine Rolle. In der deutschen Version von Confluence spielt es nicht einmal eine Rolle ob sie nach dem deutschen oder englischen Namen des Macros suchen. Sie können mit den Pfeiltasten in den aufpoppenden Ergebnissen wählen und die Auswahl mit Enter übernehmen. Tippen Sie danach vier Minuszeichen (—-) um eine horizontale Trennlinie einzufügen. Danach {page properties report.

Das wars. Die erforderlichen Elemente wurden der Seite hinzugefügt. Mit der Trennlinie sogar noch ein wenig Markup. Belassen Sie es vorerst dabei und klicken Sie auf Save (Speichern). Um die Controls mit Funktionalität zu versehen muss erst einmal ein Template angelegt werden, dass von der Seite erstellt werden kann. Gut das dies genauso schnell geht.

Release v.x.x.x

Das Template das auf der Seite Release planning erstellt wird trägt als Namen einen Platzhalter. Die Versionsnummer sollte man im Namen eintragen. So sind die Seitennamen immer einzigartig und Confluence bekommt keine Probleme. Die Versionsnummer erscheint so auch im Link zur Seite und ist so angenehm referenzierbar.

Sections zum definieren des Layouts der Seite

In diesem Template nutzen wir Sections (Bereiche) um das Layout genauer festlegen zu können.

Eine Section ist dabei ein Reihe in der jeder gewünschte Content eingefügt werden kann. Jeder Section kann noch in Columns aufgeteilt werden. Die genaue Benutzung kann hier wieder der Anleitung von Confluence entnommen werden. Aber Männer lesen keine Anleitungen.

Für das Template werden 4 Sections benötigt.

Page Properties

Wählen Sie das 2-Spalten-Layout für die Erste und tippen Sie {page properties. Es entsteht ein rechteckiges Kästchen. Fügen Sie hier in die linke Spalte eine zweispaltige Tabelle ein (in der vorherigen Abbildung können Sie ein Beispiel sehen). Die linke Spalte wird als Heading column definiert. Dies geschieht mit einem der Buttons des Editors. Übernehmen Sie die Namen in der Linken Spalte in Ihre Tabelle.

Target release	x.x.x
Epic	JIRA-Link to Epic
Requirements	Link to requirement page
Document owner	Document owner
Designer	Designer
Developers	Developer
QA	QA

Die Texte in der rechten Spalte werden als Platzhalter eingefügt. Dafür steht im Editor ebenfalls ein eigener Button zu Verfügung. Platzhalter werden nur im Editor angezeigt, solange noch kein eigener Text für den Platzhalter geschrieben wurde. Sie werden nicht auf den Seiten selbst angezeigt.

In einem Menü, dass bei der Eingabe oder bei einem Klick auf den Text erscheint können Sie auswählen was passieren soll, wenn später ein Benutzer beim Anlegen einer Seite auf den Text klickt. Platzhalter können einfacher Text sein. Es kann aber auch ein Benutzer oder ein JIRA-Issue angegeben werden. In diesen Fällen öffnen sich andere Dialoge bei dem Ausfüllen des Platzhalters, wenn aus dem Template eine Seite erzeugt wird.

Wählen Sie folgende Einstellungen für die Platzhalter.

• x.x.x – Text
• JIRA-Link to Epic – JIRA Macro
• Link to requirement page – Link zur Projektanforderungsseite zu dieser Releaseplanung
• Document owner, Designer, Developer und QA – User mention

Todo-Liste

In der rechten Spalte der ersten Section fügen Sie eine TODO-Liste ein. [] erstellt eine solche. Hier ist der Inhalt der Liste:

• User Create the Design Hub for Mockups
• User Create notes about competitor insights
• User Create a place to collect all worknotes
• User Create a place for test criteria and results

Die Liste soll daran erinnern was noch gemacht werden muss nachdem eine Releaseseite erstellt wurde. Die User sind wieder User mentions für die Benutzer, die die Aufgabe ausführen sollen. Also wahrscheinlich Sie selbst.

Eine zweite Liste kann später genutzt werden um offene Fragen festzuhalten.

Roadmap

In der zweiten Section tippen Sie {roadmap. Hiermit erstellen Sie ein Diagramm um den Zeitplan festzuhalten.

Issue-Tracking

In der dritten Section tippen Sie {jira. Im Dialog des JIRA Macros können Sie einen Filter eintragen mit dem Sie nach offenen Issues eines Projekts filtern können. Diese werden dann in einer Tabelle auf der Seite angezeigt.

Leider müssen Sie hier einen JIRA-Projekt-Key eintragen um den Filter ausfüllen zu können.

Wiki-Verknüpfungen

In der letzten Section tippen Sie {related pages. Setzten Sie im Dialog den Haken bei Show Descendants um die Seitenhirachie darstellen zu können. Sie bekommen mit dem Macro ein Inhaltsverzeichnis.

Jetzt kitten wir alles zusammen. Die Releaseseite soll in der Lage sein, diese Seite zu erstellen. Sie muss also wissen welches Template sie benutzen soll um eine Seite zu erstellen. Außerdem soll die Übersichtsseite alle Releaseseiten in einer Tabelle darstellen.

Zuerst die letzte Vorbereitung. Wir geben unserem Template ein Label. Alles Seiten die aus dem Template erstellt werden haben dann automatisch dieses Label und können später auch anhand des Labels identifiziert werden. Klicken Sie im Editor dazu auf das Label-Symbol und tippen release-planning.

Nun ist dieses Template fertig und kann gespeichert werden. Wechseln Sie zurück zum vorher angelegten Template. Klicken Sie auf das Create from template-Macro und wählen Sie im Dialog das neue Template aus.

Für das Page properties report-Macro wählen Sie als Label nun release-planning. Nun ist alles konfiguriert. Das Macro sucht sich nun alle Child-Pages mit dem entsprechenden Label und zeigt in der Tabelle nützlicher Weise die Werte der Tabelle in der Page-Properties-Box an. Sehr schön.

Mit diesen Techniken können jetzt auch die anderen Templates implementiert werden.

Competitor insight

Seiten vom Typ Competitor insight sollen genutzt werden um Lösungsansätze von Konkurrenzprodukten zu untersuchen.

Competitor insights

Die Competitor insights bildet die Parent-Seite um die Untersuchungen der Wettbewerber zusammenzufassen. Neue Competitor insght-Seiten können hier mit einem Button erstellt werden. Es wird eine tabellarische Übersicht der Unterseiten angezeigt. Die Seite wird so implementiert wie es im Release-Beispiel beschrieben ist.

Design note

Desing notes beschreiben das Design der Anwendung. Hier können sowohl Mockups oder eine Beschreibung der Programmsteuerung gesammelt werden. Auch Farbschemen oder andere Layoutentscheidungen können mit diesem Dokument beschrieben werden.

Bereich zum Sammeln von Designdokumenten

Der Design hub ist die Parent-Seite für Design notes und wird wie das Release-Beispiel oder die Competitor insights implementiert.

Issue

Das Issue-Template soll alle Informationen bei der Implementation eines JIRA-Issues festhalten. Es soll beschreiben was erreicht werden soll. Es soll festhalten was die Anforderungen an die Lösung sind und alle erdenklichen Informationen wie Links, Gedanken, Lösungsansätze ect. festhalten die bei der Umsetzung des Issues auftreten.

Worknotes

Worknotes ist die Parent-Seite für Issue-Seiten und andere Notizen die während der Entwicklung der Anwendung gemacht werden. Sie unterscheidet sich in der Umsetzung nicht vom Design hub oder den Competitor insights.

Testcase

Testcase beschreibt einen Testfall. Das heißt, er beschreibt was getestet werden soll. Er beschreibt Schritt für Schritt wie die Testumgebung hergestellt werden soll und er beschreibt das erwartete Ergebnis. Das Dokument ist nicht gedacht um Unittests zu beschreiben. Alle Tests die automatisiert durchgeführt werden können sollten sich durch ihre Konfigurationsdateien oder durch Code weitestgehend selbst dokumentieren. So sollte die Liste also recht übersichtlich bleiben. Sie sollte sich überwiegend aus Integrationstests zusammensetzen, die manuell durchgeführt werden müssen um die Software nach dem Verteilen auf korrekte Funktionsweise zu testen.

Testing

Testing ist die Parent-Seite für Testcases. Hier lassen sich aber auch gut andere, mit Tests in Zusammenhang Stehende, Dokumente speichern. Beispielsweise Anleitungen wie man diverse automatisierte Tests ausführt oder welche VMs genutzt werden sollen. Was hier an Dokumentation gespeichert wird hängt davon ab wie Ihr arbeitet und testet.