Wenn Sie mir versprechen, dass Sie sich von Vorurteilen gegenüber Dokumentationsaufgaben verabschieden, kommen hier die Tools, die den Prozess schmerzfrei gestalten. Diese Tools sind nicht nur effizient, sondern auch teamübergreifend nutzbar, helfen bei der Versionierung und bieten die Möglichkeit schnell Unterschiede in der Dokumentation zu erfassen. Mit ausdrucksstarker Markup-Sprache und Multi-Repo Docs wird die Dokumentation zum Kinderspiel. Es ist wirklich kein Hexenwerk!
AsciiDoc ist eine umfassende und trotzdem schnell zu erlernende Markup Sprache. Von Textformatierung über Tabellen und Bildern bis zur automatischen Generierung von Inhaltsverzeichnissen bleibt kein Wunsch unerfüllt. Und am Ende können Sie das Ergebnis als PDF oder Webseite erzeugen lassen.
Mit Antora können Sie die Dokumentation mehrerer Teilkomponenten aus verschiedenen Git-Repositories zu einer Webseite zusammenführen. Dabei ist auch eine Versionierung möglich und das Generieren von Dokumentation für mehrere parallele Versionen.
Für eine Dokumentation, die sich an Nutzende richtet, ist ein einheitliches Sprachbild sinnvoll. Große Firmen wie Microsoft oder Google haben dafür einen Editorial Styleguide aufgestellt. Dieser regelt Fragen der Groß- und Kleinschreibung sowie Punktation in Überschriften oder auch die maximale Satzlänge. So bleibt die Dokumentation sprachlich konsistent, auch wenn mehrere Menschen daran arbeiten.
Mit Vale (vale.sh) kann man diese Regeln aufstellen und automatisiert prüfen. Und es gibt auch fertige Regelpakete, welche direkt genutzt werden können.
