arc42 Confluence Template Start

Owned by Ralf D. Müller
Last updated: Jan 22, 2017
3 min read

Looking for the English version of the template?

Suchen Sie die englische Version des Templates?

Willkommen auf dem arc42 Confluence Template Space. Hier finden Sie alle nötigen Informationen um Ihre Software-Architektur mit arc42 in Confluence zu dokumentieren.

Allerdings haben Sie mehrere Optionen das arc42-Template mit Confluence zu nutzen:

1) Template runterladen und als Confluence Space installieren

Das Template gibt es für jede Sprache in zwei Geschmacksrichtungen, die wir als "flat" und "structured" bezeichnen. Der Unterschied liegt nur in der Anzahl der Confluence-Seiten auf die das Template aufgeteilt wird. Die "flache" Version besteht nur aus einer Seite pro Top-Level Kapitel. Also 12 Seiten insgesamt. Die "strukturiertere" Version verfügt über jeweils eine Seite für jede Level-2-Überschrift.

Beide Versionen können hier runtergeladen werden:

Sie können die Bereich aber auch jederzeit selbst exportieren - der anonyme User verfügt über die entsprechenden Berechtigungen.

Die Dokumentation, wie dieser Space importiert werden kann, finden Sie in der Confluence Dokumentation: Import a Confluence Space

Vorteile:

  • einfach umzusetzen
  • ein Confluence-Space pro Projekt

Nachteile:

  • Sie benötigen Administrator-Rechte um einen Space importieren zu können
  • der Import ist stark abhängig von der Confluence-Version


Pro-Tipp :-)

Möchten Sie Ihre Dokumentation veröffentlichen? In dieser Confluence-Instanz ist noch viel Platz - kontaktieren Sie uns einfach!

2) Benutzen Sie eines der Confluence arc42-Plugins

Im Atlassian Marketplace gibt es zwei Confluence-Plugins, die Sie bei der Dokumentation mit arc42unterstützen:

Probieren Sie sie einfach mal aus!

Vorteile:

  • unterschiedlich, abhängig vom Plugin

Nachteile:

  • Sie müssen in Ihrer Confluence-Instanz Plugins installieren können (die Plugins sind z.B. nicht für die Cloud-Instanzen verfügbar)

3) Importieren Sie arc42 mit docToolchain

docToolchain ist ein open source Gradle-Projekt mit dem sich AsciiDoc Dokumente leicht in verschiedene Ausgabeformate wandeln lassen. Das Projekt funktioniert recht gut, ist aber noch nicht sehr gut dokumentiert:

  1. laden Sie das Gradle-Projekt von Github runter: https://github.com/rdmueller/docToolchain/archive/master.zip
    Es enthält schon das arc42-Template vorinstalliert und enthält den Gradle-Wrapper. Somit benötigt es nur eine funktionsfähige Java-Version zum Laufen.
  2. konvertieren Sie das Asciidoc arc42-template nach HTML:
    ./gradlew
    die HTML-Version liegt anschliessend im build-Verzeichnis
  3. konfigurieren Sie Ihren Zugriff auf Confluence:
    öffnen Sie die Datei./scripts/ConfluenceConfig.groovy und ändern Sie die Konfiguration entsprechend Ihren Wünschen und Ihrem Setup.
  4. Importieren Sie das arc42-Template über die Confluence REST-API direkt in Ihren Confluence-Space
    ./gradlew publishToConfluence
  5. schreiben Sie Ihre Architekturdokumentation mit Confluence als Master

Wenn Sie bezüglich der Weiterentwicklung von docToolchain auf dem Laufenden bleiben wollen, können sie dem Twitter-Account @docToolchain folgen. Benötigen Sie Unterstützung, stellen Sie bitte entsprechende Problembeschreibungen im Github Issue-Tracker ein.

Vorteile:

  • durch ein Präfix der Seitennamen können mehrere Kopien des Templates in einem Confluence-Space verwaltet werden
  • der Vorgang benötigt keine Admin-Rechte

Nacheile:

  • sehr technisch

4) Benutzen Sie docToolchain zum Export nach Confluence

Mit docToolchain können Sie nicht nur das arc42-Template nach Confluence importieren, Sie können auch das AsciiDoc-Template als Master verwenden. Befolgen Sie einfach die unter 3) beschriebenen Schritte und schreiben Sie Ihre Dokumentation in Asciidoc im./src/docs - Verzeichnis des Gradle-Projekts. Immer wenn Sie anschließend die Dokumentation in Confluence updaten wollen, können Sie die AsciiDoc-Dokumentation exportieren, indem Sie

.gradlew

gefolgt von

./gradlew publishToConfluence

ausführen.

Vorteile:

  • Docs-as-Code Ansatz: nutzen Sie die selben Tools für Ihre Dokumentation wie für Ihren Source-Code
  • nutzen Sie z.B. PlantUML für Diagramme ohne das Confluence-Plugin installieren zu müssen
  • nutzen Sie alle Vorteile von AsciiDoc zusammen mit den Featuresvon Confluence (Seiten beobachten, Kommentare etc.)

Nachteile:

  • noch technischer als 3)
  • verfügt über keinen Editor wie Confluence


Thanx!

PS: an dieser Stelle ein großes Dankeschön and Atlassian für die Bereitstellung dieser Confluence-Instanz!