Vortrag: 10:30-11:15 (deutsch)

Effizient arbeiten mit Architecture Decision Records (ADR)

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.

Johannes Dienst

@johannesdienst

Johannes Dienst ist ein Softwarecraftsman aus Leidenschaft bei der DB Systel GmbH. Sein Tätigkeitsschwerpunkt liegt im Bereich Content Management, DevOps und Softwarequalität.

Video
https://media.ccc.de/v/bob2020-108-effizient_arbeiten_mit_architecture_decision_records_adr