Ein wohldefiniertes REST-API ist heutzutage ein Must-have. Wesentlicher Erfolgsfaktor ist neben dem API-Design insbesondere eine ansprechende technische Dokumentation. Der Dokumentation wird ein nahezu epischer Wartungsaufwand nachgesagt. Die These, sie sei bereits im Moment der Erstellung veraltet, hält sich hartnäckig.
Je dynamischer ein Projekt und je manueller die Prozesse, umso zutreffender sind diese Aussagen. Die Wahl der passenden Werkzeuge in einem strukturierten Prozess schafft hier schnell Abhilfe. Wesentlicher Erfolgsfaktor ist ein Höchstmaß an Automatisierung und Kooperation sowie ein auf die jeweiligen Bedürfnisse der Beteiligten abgestimmtes Tooling. API-Design, Code und Dokumentation wachsen gemeinsam, bei minimalem Wartungsaufwand und maximaler Konsistenz.
Das Problem mit den Schwiegereltern
Liebe auf den ersten Blick gibt es auch bei Technologien, und der erste Eindruck zählt nicht nur bei den Schwiegereltern. Das erste Date mit dem zukünftigen API findet meist über die Dokumentation statt. Sie erwächst dadurch von einem oft stiefmütterlich behandelten Softwareartefakt zu einem zentralen Marketinginstrument. Als Bindeglied zwischen prosaischer, marketingorientierter fachlicher Domänenerklärung im Businesssprech und einer detaillierten, aussagekräftigen technischen API-Spezifikation sind Quickstart Guides häufig der gemeinsame Nenner mit den „Schwiegereltern“. Und diese Schwiegereltern gilt es zu überzeugen. Entwicklern liegt das Verfassen von öffentlichkeitstauglicher Prosa nicht unbedingt, das überlässt man lieber einem Technical Writer. Dem fehlt aber wieder ein tieferes technisches Verständnis.
Spätestens bei Quickstarts oder technischen Details der Domäne ist der Input der Entwickler gefragt. In den meisten Fällen werden also unterschiedliche Abteilungen an der Gesamtdokumentation arbeiten. Um die Effizienz aller Beteiligten gewährleisten zu können, muss jeder Einzelne in seiner gewohnten Umgebung mit den jeweils bevorzugten Tools arbeiten. Aus den einzelnen Quellen muss dennoch ein konsistentes Gesamterlebnis erstellt werden. Neben einer einheitlichen User Journey ist die Aktualität die zentrale Anforderung an eine Dokumentation. Diese zu gewährleisten ist umso aufwendiger, je näher sie sich am Code bewegt. Somit ist bei der Dokumentationserstellung nicht nur der Aspekt der Kosteneffizienz, sondern insbesondere die dauerhafte Wartung ein relevanter Faktor. Effizienz und Wartungsaufwand lassen sich durch Automatisierung in den Griff bekommen. Mit nur wenigen Open-Source-Tools lässt sich ein Prozess etablieren, der es den Technical Writers und Redakteuren ermöglicht, beispielsweise im Firmenwiki zu arbeiten, während die Entwickler ihren Anteil aus der bevorzugten IDE beitragen. Das Herz der Dokumentation, API-Spezifikation und Codebeispiele, wird ohne manuellen Aufwand mit Aktualitätsgarantie automatisiert aus dem Quellcode generiert. Alle Artefakte werden auf Knopfdruck in ein homogenes Gesamtdokument konvertiert und nach Belieben als HTML, PDF oder Word-Dokument zur Verfügung gestellt. Die Schwiegereltern werden es lieben, und der Onkel freut sich über die generierten Postman Collections für die Abnahmetests.
Gradle und Asciidoctor verbinden die Welten
Jeder arbeitet am liebsten und effizientesten in seiner gewohnten Umgebung. Was für den Entwickler die IDE ist, ist für den Technical Writer Word oder das Contentmanagementsystem. Der Kompromiss zwischen den Welten ist häufig das von beiden genutzte Firmenwiki. Ein Wiki ist aber nur begrenzt für die Veröffentlichung einer Website geeignet und einige Entwickler scheuen den Kontextwechsel aus der IDE in ein WYSIWYG-Tool. Content aus unterschiedlichen Quellen in einem Wiki zusammenzuführen, ist nicht immer einfach. Meist erfolgt es durch redundantes Kopieren der Inhalte. Die meisten Wikis zeichnen sich dadurch aus, dass sie Markup-Sprachen verarbeiten und produzieren können. Zusätzlich bieten einige auch APIs an, mit denen Inhalte abgerufen und importiert werden können. Neben unterschiedlichen Quellen wie Text, Source Code oder Diagrammen liefern auch unterschiedliche Beteiligte Input zur Dokumentation. Nicht jeder Entwickler ist auch ein guter Autor und auch im besten Fall erschweren unterschiedliche Schreibstile ein konsistentes Leseerlebnis. Der Redaktion kommt somit die Verantwortung für das Lektorat zu, meist verbunden mit einer Überarbeitung des eher an Entwicklernotizen erinnernden Inputs. Es kommt zu einer dauerhaften Synchronisation zwischen prosaischer Dokumentation und dem tatsächlichen Stand der Software. Source-Code-Beispiele aus der Dokumentation stimmen schnell nicht mehr mit der Realität überein, die Dokumentation ist obsolet. Das lässt sich verhindern, wenn die Dokumentation, insbesondere die veröffentlichte, in die Verantwortung der Entwickler fällt. Der daraus resultierende Mehraufwand wird in der Entwicklung jedoch nicht unbedingt auf Gegenliebe stoßen. Um die ungeliebten Tätigkeiten zu reduzieren, kann das Entwicklerwissen an der Quelle angezapft werden. Häufig liegt der relevante Input bereits in Form von interner Dokumentation vor. Öffentlichkeitstauglichere Inhalte finden sich eventuell in den Readmes des Git-Repos. Zusätzlicher Input findet sich in Release und Change Notes und kann durch die Entwicklung leichtgewichtig um Textfiles ergänzt werden. Markdown oder das ausdrucksstärkere AsciiDoc ermöglichen es, in reinen Textfiles strukturierten und formatierten Text zu erstellen. Für eine statische Prozessierung der Markdown-Files ist Asciidoctor [2] das Mittel der Wahl und wurde im Kontext des Docs-as-Code-Ansatzes ausführlich beschrieben [3] und mit der docToolchain [4] um eine mächtige Toolsammlung ergänzt.
Getrennt gepflegter Inhalt kann mit Asciidoctor einfach zusammengeführt werden. Die geschaffene Basis lässt sich um von der Redaktion überarbeitete Entwickler-Notes erweitern. Die als .adoc vorliegenden Entwicklernotizen werden wie in [4] gezeigt in eine abgestimmte Seitenhierarchie in Confluence importiert. Aus diesem Bereich überträgt die Redaktion die Bullet Points in die aufbereitete Dokumentation, von wo sie wiederum in obigem Schritt reimportiert wird. Es bedarf nicht allzu viel Fantasie, um zu erkennen, dass ein Build-Prozess auf Repository Changes der Entwickler-.adocs lauscht und geänderte Files automatisch in Confluence pusht. Der Notification-Mechanismus von Confluence übernimmt die Benachrichtigung der Redaktion.
Um einen kollaborativen Prozess bei der Dokumentationserstellung zu etablieren, dienen Asciidoctor und ein wenig Gradle als zentrales Tooling. Mit Asciidoctor lässt sich der in Markup vorliegende Input in ansehnliche Dokumente, beispielsweise HTML oder PDF, verwandeln. Gradle dient der Automatisierung der Zusammenführung der unterschiedlichen Quellen. Die Hauptseite aus Listing 1 organisiert die Struktur der Dokumentation. Die einzelnen Bestandteile werden aus eigenständigen Dateien importiert und in das Gesamtbild integriert.
Listing 1: Hauptseite der Dokumentation
= heidelpay Payment Api
// basic config ommitted
:snippets: ../../
:section-dir: ../../build/generated-snippets
= Introduction
[section]
====
include::{section-dir}/confluence/Info.adoc[]
include::diagrams/pay_sequence.adoc[]
====
== API
== Charge
No matter which payment-method you choose, the implementation of charge is kept
consistent. You will always pass the amount as a request parameter together with
the payment-methods details as body.
=== Credit Card
==== Request
include::{section-dir}/restdoc/charge/curl-request.adoc[]
===== Parameter
include::{section-dir}/auto-adoc/charge/auto-request-parameters.adoc[]
===== Body
include::{section-dir}/auto-adoc/charge/auto-request-fields.adoc[]
==== Response
include::{section-dir}/restdoc/charge/response-body.adoc[]
include::{section-dir}/restdoc/charge/response-fields.adoc[]
=== SEPA
More comes here...Der in Abbildung 1 gezeigte Abschnitt wird aus unterschiedlichen Quellen zusammengestellt. Die einleitende Tabelle samt Hinweisen wird redaktionell im Wiki (Confluence) gepflegt und ist über include::{section-dir}/confluence/Info.adoc[] in die Dokumentation integriert. Das Sequenzdiagram ist, wie in [3] beschrieben, im Textfile aus Listing 2 als .adoc definiert. Für die Prozessierung des PlantUML-basierten Sequenzdiagramms wird das asciidoctor-diagram-Plug-in [5] eingesetzt. Dieses ist zunächst auf den Asciidoctor-Einsatz auf der Kommandozeile beschränkt und muss dem Gradle Build als RubyGem zugänglich gemacht werden (Listing 3). Darüber hinaus hängt die Diagrammgenerierung von asciidoctor-diagram von extern installierten Tools (hier Graphviz) ab. Alternativ kann über Viz.js [6] als Prozessor injiziert werden (...

