Dokumentation gehört oft nicht zu den Lieblingsaufgaben im
Softwareentwicklungsalltag. Das resultiert in vielen Fällen daraus,
dass 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.