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:

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:

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

TAGS