Annahme: Sie kennen arc42
Ich gehe in diesem Blogpost einfach davon aus, dass Sie arc42 zumindest in Grundzügen kennen (Falls nicht, finden Sie hier einen kompakten Überblick und dort viele Beispiele ).
Warum überhaupt eine neue Version?
Die Vorversion (arc42 V6) war über 4 Jahre in Produktion, und wurde von zahlreichen Teams zur Dokumentation und Kommunikation von Softwarearchitekturen verwendet. Allerdings hatten sich aufgrund der damals noch heterogenen Werkzeugkette über die Zeit viele kleine Inkonsistenzen eingeschlichen, insbesondere in den umfangreichen Hilfe- und Erläuterungstexten.
Version 6 basierte aus historischen Gründen ursprünglich auf docx, und wurde 2014 auf AsciiDoc umgestellt. Leider wurden dann diverse Formate (u.a. Confluence und teilweise auch docx) nur noch manuell gepflegt.
Die meisten Nutzer von arc42 gaben positive Rückmeldung zur grundsätzlichen Struktur, forderten aber eine verbesserte Hilfe, sowie bessere Unterstützung bei der praktischen Arbeit mit arc42 (etwa durch durchsuchbare FAQ).
Highlights von Version 7
Die arc42-Gründer (Peter Hruschka und Gernot Starke) haben Ende 2016 die verschiedenen Versionen von V6 konsolidiert, gründlich aufgeräumt, alle Texte homogenisiert und deutlich kompakter formuliert. Die bewährte Struktur aus 12 Sektionen blieb dabei vollständig erhalten. Auch deren Namen sind (fast) geblieben: Einzig Teil 11 wurde zu „Risiken und technische Schulden“ erweitert. Damit bleibt arc42 Version 7 vollständig kompatibel zur Vorgängerversion.
Mit V7 ist das arc42-template Github-Repository endgültig zum einzigen Master von arc42 geworden. Aus den darin verwalteten AsciiDoc Sourcen generiert eine Kombination aus Gradle, Pandoc und etwas Groovy-Magie die meisten der geforderten arc42 Zielformate (u.a. docx, Markdown, LaTeX, html, pdf). Confluence-Spaces können dank der Beiträge von Ralf D. Müller (Autor der DocToolChain) ebenfalls aus diesem Master generiert werden.
Den wohl größten Sprung hat arc42 allerdings mit den Neuerungen im Ökosystem gemacht. In Kurzform:
- Eine umfangreiche Dokumentation-Website, docs.arc42.org
- Eine umfangreiche FAQ-Website, faq.arc42.org
- Kommentar- und Diskussionsforen sowohl bei Tipps wie auch FAQ
- Eine öffentliche Slack-Gruppe, in der Interessierte fokussiert auf arc42 Themen diskutieren oder Fragen stellen können
- Eine komplett neue Community-Website (arc42.org)
Neu: Tipps und Hilfe
Die Tipps- und Hilfeseite docs.arc42.org enthält einerseits das komplette Template, andererseits ausführliche Tipps zur Anwendung - gegliedert nach den einzelnen arc42-Sektionen.
Am Ende jeder Sektion finden sich dort Verweise auf alle zugehörigen Tipps und Ratschläge - ausführlich katalogisiert mit Schlagworten. Drei dieser Begriffe möchte ich hier kurz hervorheben:
- lean: Ratschläge für sparsamen Einsatz von arc42, etwa für kleinere, agile Projekte. Tipps dieser Kategorie sparen Zeit und Aufwand für Dokumentation, gehen oftmals jedoch auf Kosten der Gründlichkeit.
- Mit thorough bezeichnet Tipps helfen bei großen Systemen oder besonders kritischen Systemen, die oftmals in eher formalen Prozessen entstehen. Diese Tipps kontrastieren mit den Spar-Tipps aus der Lean-Gruppe.
- Schliesslich kennzeichnen essential Ratschläge fundamentale Grundlagen der Architekturdokumentation - meist übrigens auch ziemlich lean…
Neu: FAQ
Die FAQ-Seite faq.arc42.org bildet das Pendant zur Dokumentation-Seite: Über 120 (Tendenz steigend) Antworten auf die häufigsten Fragen rund um arc42 - ebenfalls komplett verschlagwortet und durchsuchbar.
Beide Sites basieren auf dem statischen Site-Generator Jekyll und werden via Github-Pages aus öffentlichen Repos generiert. Jekyll-Interessierte finden in den Github-Repos die von arc42 angepassten Themes - die sich sicherlich auch für andere Projekte nutzbringend einsetzen lassen.
Relaunch der Community-Website
Hauptsächlich für internationale arc42 Nutzer gibt es eine rundum erneuerte arc42.org community-Site, die auch sämtliche Downloads des Templates enthält.
Neu: Mehr Interaktion
Eine wesentliche Neuerung seit Anfang 2017 betrifft dieCommunity-Aktivitäten von arc42: Neben einer öffentlichen Slack-Gruppe gibt es in den Tipps sowie FAQ überall Kommentar- und Fragemöglichkeiten. (Auf dieser Seite können Sie sich selbst zum arc42-Slack einladen.)
In dieser Gruppe finden sich bereits zahlreiche arc42-Committer und -Anwender, was kurzfristige und praxisnahe Reaktionen auf alle Art Fragen verspricht.
Fazit
Mit Version 7 ist strukturell (zum Glück) bei arc42 alles beim Alten geblieben - Kompatibilität ist gewährleistet.
Deutlich kompaktere und präzisere Hilfen und Tipps machen die Arbeit mit der neuen Version (noch) leichter. Dafür sorgt auch das erweiterte Ökosystem. Ich freue mich auf Ihre Rückmeldung.
Danke
Danke an Ralf D. Müller, Peter Hruschka, Falk Hoppe, Sven Johann und Niele Schulz für ihre Beiträge zu V7.
Links
- arc42 Einstieg: arc42.org
- arc42 Doku und Tipps: docs.arc42.org
- arc42 FAQ: faq.arc42.org
- arc42 Beispiele