Leider hält sich in vielen Bereichen immer noch hartnäckig das Gerücht, das für eine ordentliche Dokumentation eine Textverarbeitung notwendig ist.
Üblicher und übler Vertreter dieser Gattung ist Microsoft Word. Die Nachteile durch dieses Programm für Software Entwickler sind nahezu endlos. Programmfehler, komplizierte Bedienung, Ablenkung von Inhalt durch WYSIWYG, Inkompatibilitäten zu anderen Programmen oder eigenen älteren Versionen, automatisierte Dokumentationstools unterstützen das Format nicht.
Als Alternative zu Textverarbeitungsprogrammen nutzen Software Entwickler schon seit langer Zeit Textprozessoren. Textprozessoren lesen eine Textdatei ein und formatieren den Text anhand einiger Befehle, die im Text eingefügt wurden.
Klassische Vertreter sind TROFF und all seine Derivate, sowie \TeX und sein bekanntester Aufsatz \LaTeX. Neuere Vertreter sind MarkDown und AsciiDoc.
Das folgende Beispiel zeigt eine TROFF Eingabe Datei.
.TH CORRUPT 1
.SH NAME
corrupt \- modify files by randomly changing bits
.SH SYNOPSIS
.B corrupt
[\fB\-n\fR \fIBITS\fR]
[\fB\-\-bits\fR \fIBITS\fR]
.IR file ...
.SH DESCRIPTION
.B corrupt
modifies files by toggling a randomly chosen bit.
.SH OPTIONS
.TP
.BR \-n ", " \-\-bits =\fIBITS\fR
Set the number of bits to modify.
Default is one bit.Die TROFF Befehle in dieser Datei stehen immer am Zeilenanfang und beginnen mit einem Punkt. Der Befehl .SH markiert den Beginn Kapitelüberschrift, der Befehl .B erzeugt Fettschrift. Diese Format existiert tatsächlich auch noch heute, denn in diesem Format ist die gesamte Online Dokumentation von UNIX erstellt. Jeder Aufruf des Kommandos man nutzt die Möglichkeiten von TROFF.
Der Ursprung des Textsatzsystem \TeX ist legendär. Weil er mit der typographischen Qualität seiner Bücher unzufrieden war, entwickelte Donald E. Knuth von 1977 bis 1986 sein eigenes Textsatzsystem. Das Paket \LaTeX vereinfacht das Arbeiten mit dem Basisprogramm.
\subsection{Formeln}
\LaTeX{} ist auch ohne Formeln sehr nützlich und
einfach zu verwenden. Grafiken, Tabellen,
Querverweise aller Art, Literatur- und
Stichwortverzeichnis sind kein Problem.
Formeln sind etwas schwieriger, dennoch hier ein
einfaches Beispiel. Zwei von Einsteins
berühmtesten Formeln lauten:
\begin{align}
E &= mc^2 \\
m &= \frac{m_0}{\sqrt{1-\frac{v^2}{c^2}}}
\end{align}Bei \TeX und \LaTeX sind die Formatierungsbefehle einfacher zu lesen und weil dem Entwickler die Darstellung von Formeln wichtig war, werden sehr viele Texte im wissenschaftlichen Umfeld noch immer mit Programmen erzeugt, die auf \TeX aufbauen.
Software Entwickler sind eher als faule Schreiber bekannt und so führte kein Weg daran vorbei, die Befehle im Text zu vereinfachen. Da die Formatierungsbefehle auch als Mark Up bezeichnet werden, erfanden John Gruber und Aaron Swartz das MarkDown Format.
# Ancestor API (v1)
Contact: _info@schegge.de_
## Servers
| URL | Description |
| --- | ----------- |
| http://localhost:8080 | Demo |
## Endpoints
### Get Ancestor
Get a **single** Ancestor
```
GET /api/v1/Ancestors/{id}
```
Überschriften sind in diesem Format mit dem # markiert. Der Titel mit einem einzigen #, ein Kapitel mit ##, ein Unterkapitel mit ###. Ein Text wird kursiv dargestellt wenn er in _ eingefasst und fett wenn er in ** eingefasst wird. Außerdem sind Verlinkungen, Tabellen und weitere nützliche Formatierungen möglich.
Mit AsciiDoc bewegt sich der MarkDown wieder in Richtung Textsatzsystem. Ist MarkDown sehr gut geeignet für kurze Online Anleitungen, so kann das leicht abgewandelte AsciiDoc mit einer Reihe von Erweiterungen glänzen um vollständige Dokumentationen zu erstellen.
Obwohl all diese Programme sehr unterschiedliche in ihren Möglichkeiten sind, haben sie doch viele Gemeinsamkeiten, die sie für Software Entwickler interessant machen.
Eine für Außenstehende sehr unscheinbare Gemeinsamkeit ist die Verwendung von einfachen Textdateien als Eingabeformat.
Textdateien, können mit beliebigen Texteditoren bearbeitet werden. Jeder Entwickler kann das Tool seiner Wahl verwenden, ob VI, GNU Emacs, Atom Notepad++, Eclipse, NetBeans, Visual Studio Code oder Intellij IDEA.
Die Dokumentation kann zusammen mit dem Sourcecode in der Versionsverwaltung gespeichert werden. Selbstverständlich können auch Word Dokumente in einer Versionsverwaltung gespeichert werden, aber Änderungen prüfen und verschiedene Versionen mergen ist damit nicht möglich. Befindet sich die Dokumentation in Textdateien, dann können Änderungen an der Dokumentation innerhalb eines Feature-Branch genauso einfach in den Main-Branch übernommen werden, wie der Source Code.
Ein letzter Vorteil von Textdateien als Dateiformat ist die Möglichkeit die Dokumentation automatisch zu erzeugen oder zu manipulieren. Eine Beispiel zur Erzeugung von Dokumentation stellt der Beitrag Trivial Pursuit – API MarkDown vor. Dort wurde aus einer OpenAPI Beschreibung im Json Format eine Dokumentation erzeugt.
Programme wie \LaTeX und AsciiDoc erlauben es Teildokumente über spezielle Befehle zu inkludieren. Hier wird beispielsweise von AsciiDoc eine Json Datei in eine Code Umgebung eingefügt.
.Example Request Body
[source,json]
----
include::{sourcedir}/de/schegge/ancestor/api/create-tree.json[]
----
Ein angenehmer Seiteneffekt ist hier die Aktualität und Korrektheit der eingefügten Beispiele. Die eingefügte Json Datei wird beispielsweise auch innerhalb eines Unit Test verwendet um die Korrektheit der API zu testen. Änderungen an der API führen zu geänderten Testdaten, die als Beispiel direkt in die Dokumentation einfließen.
Auch wenn andere Textprozessoren die Möglichkeiten nicht bieten, kann eine solche Möglichkeit durch einen Präprozessor bereitgestellt werden. Dafür muss nur die Originaldatei eingelesen werden und eingefügte Marker durch die gewünschte Datei ersetzt werden.
Pattern pattern = Pattern.compile("^include::\\{(\\w+)\}([\\w/.]+)\\[\\]$");
Map<String, Path> sources = Map.of("sourceDir", Paths.get("src/main/resources"));
String line;
while ((line = input.readLine) != null) {
Matcher matcher = pattern.matcher(line);
if (matcher.find( )) {
includeFile(output, sources.get(matcher.group(1)), matcher.group(2))
} else {
output.println(line);
}
}Der hier gezeigte Präprozessor liest die Eingabe über input ein und wenn eine Zeile der AsciiDoc Include-Anweisung gleicht, dann wird die entsprechende Datei in die Ausgabe output geschrieben. Im anderen Fall wird die Eingabezeile direkt in die Ausgabe geschrieben.
Wer als Software Entwickler seine Ergebnisse dokumentieren muss, sollte sich tunlichst überlegen, ob er sich von Außenstehende auf ein Tool wie Microsoft Word festlegen lassen will oder ein Format nutzen möchte, dass sich viel besser in die eigene Arbeitswelt einfügt.