Seite 3: Fachliche Dokumentation

Für eine fachliche Dokumentation braucht es aber mehr als Quellcode und Referenzen. Hier sind Tabellen und Diagramme gefragt, die Inhalte strukturieren und übersichtlicher darstellen können als ein langer Text. Eine einfache Tabelle sieht im Quellcode wie folgt aus:

|===
|Thema |Text |Mehr...

|Ein Thema
|Text
|Noch mehr Text

|Zweites Thema
|Text Nr. 2
|Ganz viel Text
|===

Als HTML-Ausgabe stellt es sich wie folgt dar:

Mit zusätzlichen Attributen erlaubt AsciiDoc Textausrichtung und horizontal und vertikal zusammengefasste Zellen. Für mathematisch-wissenschaftliche Darstellungen bietet es Formeln im LaTeX- und AsciiMath-Format. Aus folgendem Text wird mit MathJax in der Ausgabe eine gesetzte Formel.

stem:[sqrt(4) = 2]

Eine Matrix: stem:[[[a,b\],[c,d\]\]((n),(k))].

latexmath:[C = \alpha + \beta Y^{\gamma} + \epsilon]

UML-Diagramme wie ein Ablaufdiagramm lassen sich über PlantUML als Text beschreiben und als Grafik ausgeben:

@startuml
|Akteur A|
start
:Schritt 1;
|#AntiqueWhite|Akteur B|
' Dies ist ein Kommentar im
' Quellcode des Diagramms
:Schritt 2;
:Schritt 3;
|Akteur A|
:Schritt 4;
|Akteur B|
:Schritt 5;
stop
@enduml

Auch für diese Diagramme ist in der Versionshistorie nachvollziehbar, wer sie wann und als Teil von welcher Aufgabe warum geändert hat.

IT-Architekturdokumentation

Alle Elemente, die die fachliche Dokumentation nutzt, eignen sich auch für eine IT-Architekturdokumentation: Sie benötigt ebenso Tabellen, Diagramme, Querverweise et cetera. Um nicht bei jedem neuen Projekt von vorne zu beginnen, gibt es frei verfügbare Vorlagen. Eine solche Vorlage findet sich unter arc42.de. Sie ist in AsciiDoc geschrieben und unterstützt Projekte durch eine erprobte Dokumentationsstruktur. Projekte können sie im Projektverlauf nach und nach füllen. Erklärende Kommentare helfen beim Schreiben der Kapitel, sodass sich auch Einsteiger im Bereich Architekturdokumentation zurechtfinden.

Das arc42-Projekt zeigt außerdem, wie Dokumentations-Pipelines funktionieren: Die Vorlage wird im AsciiDoc-Format gepflegt. Daraus erstellt ein automatischer Build-Prozess verschiedene Zielformate: unter anderem Word, Markdown, HTML und reStructuredText.

API-Dokumentation mit Beispielen

Neben aufgeschriebenen Texten gibt es in Projekten immer wieder automatisch erzeugte Inhalte. Das sind zum Beispiel technische Datenmodelle, die man aus dem Datenbankschema erzeugt, oder Listen von Fehler-Codes und -beschreibungen, die Entwickler im Programm als Konstanten hinterlegt haben und aus denen Handbücher generiert werden. Hier hilft eine einfache Template-Sprache wie Freemarker, um Dokumentationsteile automatisiert zu erstellen.

Das Konzept von Spring REST Docs geht noch etwas weiter: Es nutzt für die Dokumentation von REST-Schnittstellen Beispielanfragen und -antworten, die in automatisierten Testfällen aufgezeichnet werden. Diese ergänzt man um zusätzlichen erklärenden Text. Das Ergebnis ist eine Dokumentation, die mit konkreten Beispielen zeigt, wie die Schnittstelle genutzt werden soll. Im Vergleich zu einer Schnittstellendokumentation im OpenAPI-Format, die nur Methoden und Felder zeigt (Syntax und ggf. etwas Semantik), ist das ein deutlicher Zugewinn von Verwendung und Bedeutung (Pragmatik): Die verschiedenen Aufrufe und Felder werden in einen Kontext gesetzt im Ablauf gezeigt.

Neben dem vorgestellten AsciiDoc-include-Makro bringt Spring REST Docs ein zusätzliches operation-Makro mit, das aufgezeichnete Elemente (Snippets) einbindet. Hier ein Auszug aus einem offiziellen Beispiel des Spring-REST-Docs-Projekts:

=== Listing notes

A `GET` request will list all of the service's notes.

operation::notes-list-example[snippets='response-fields,curl-request,http-response']

Ein Test zeichnet die Antworten auf und prüft, ob die erwarteten Felder in der Antwort enthalten sind:

@Test
public void notesListExample() throws Exception {

  /* .... */

  this.mockMvc.perform(get("/notes"))
    .andExpect(status().isOk())
    .andDo(document("notes-list-example",
        responseFields(
            subsectionWithPath("_embedded.notes").description("An array of [Note](#note) resources"),
            subsectionWithPath("_links").description("Links to other resources"))));
}

Das operation-Makro fügt in der Ausgabe die Beschreibung der Antwortfelder, den Aufruf als curl-Befehl und die HTTP-Antwort im JSON-Format ein:

Analog zur Entwicklerdokumentation, die per include getestete Codebeispiele anzeigt, entsteht hier eine Schnittstellendokumentation mit getesteten Beispielen.