Dokumentation gehört oft nicht zu den
Lieblingsaufgaben im Softwareentwicklungsalltag. Das
resultiert in vielen Fällen daraus, da nicht klar ist, warum
etwas dokumentiert werden sollte. Der in der Praxis gelebte
Ansatz einen Dokumentationsort, zum Beispiel in Form eines
Wikis, ist zum Scheitern verurteilt. Entweder es wird kaum
dokumentiert oder zu viel und es wird schwer Informationen zu
finden, die man sucht.
Ein leichtgewichtiger Ansatz ist arc42, bei dem je nach Bedarf
die vorgegebenen Unterpunkte ausgefüllt werden. Dort werden im
Unterpunkt neun Entwurfsentscheidungen dokumentiert, also
genau die Entscheidungen, die die Softwarearchitektur
entscheidend prägen. Die Auswirkungen von nicht dokumentierten
Entscheidungen gehen von immer wiederkehrenden Diskussionen,
bis hin zu fehlerhaften Folgeentscheidungen die das Projekt
zum Scheitern bringen können. Doch wie können viele
Entscheidungen effizient und nachvollziehbar dokumentiert
werden?
In diesem Vortrag wird ein kompaktes Format namens
Architecture Decision Records (ADR) vorgestellt und gezeigt,
wie sie effizient eingesetzt werden können. Neben
Kleinigkeiten wie der Titelvergabe für eine ADR wird ein
Lösungsvorschlag aufgezeigt, um bei einer großen Sammlung von
Entwurfsentscheidungen (>50) nicht den Überblick zu
verlieren. Dabei kommt der Docs-As-Code Ansatz mit AsciiDoc
und JBake zum Einsatz, mit dem die technische Architektur in
einer Microsite gerendert wird. Durch Tagging und eine
effiziente Suche, wird die Dokumentation nicht nur lebendig,
sondern zum täglichen Arbeitsmittel.