Top-Tools für Architekturdokumentation

Persönlich halte ich die Werkzeugfrage bei der Dokumentation von Softwarearchitektur für überbewertet. Regelmäßig wird viel Energie in die Tool-Auswahl verschwendet. Mitunter ist nicht einmal klar, für welche Zielgruppe(n) die Dokumentation überhaupt angefertigt werden soll. #fail

Das ändert allerdings nichts daran, dass Sie Dokumentation mit Werkzeugen anfertigen. Die Toolfrage wird recht schnell relevant. Gerade wenn Sie nicht im Nachhinein dokumentieren wollen, sondern Ihre zentralen Lösungsansätze bereits früh anfangen festzuhalten (was wir empfehlen).

Hier die vier unseres Wissens nach in Projekten aktuell am häufigsten eingesetzten Tools (bzw. Tool-Kategorien) für Architekturdokumentation:

Word

Wiki

UML-Tool

Versionsverwaltung + «txt»

Das «txt» bei der letzten Alternative steht dabei für ein textbasiertes Format. Dateien in diesem Format werden dann in der Versionsverwaltung (Git, Subversion, …) abgelegt. Wir haben in Projekten als Formate dazu bereits gesehen: Markdown, AsciiDoc, DocBook, LaTeX, Xdoc.

Werkzeuge unterstützen Sie beim Erstellen der Dokumentation, beim Pflegen und Verwalten, und beim Kommunizieren. Unterschiedliche Werkzeuge haben dabei unterschiedliche Stärken und Schwächen. Die folgende Tabelle verdichtet häufig aufgeführte Argumente für bzw. gegen den Einsatz der Tools im Zusammenhang mit Architekturdokumentation:

	Oft genannte Stärken ...	... Schwächen und Gefahren
Word	(+) hohe Verbreitung, in der Regel im Projekt verfügbar (+) jeder im Team kann es benutzen (+) gute Unterstützung für Formatierung, Tabellen, ... (+) gute Ergebnisse bei Bereitstellung als Druck oder PDF (+) Änderungsverfolgung erlaubt gemeinsames Arbeiten	(-) kostenpflichtig und mitunter plattformabhängig (-) gemeinsames Bearbeiten nur beschränkt möglich, insbesondere bei umfangreichen Dokumenten (-) Ermitteln von Änderungen im Dokument ohne Änderungsverfolgung schwierig (-) Für Abbildungen in der Regel weiteres Werkzeug erforderlich (-) Freiheit beim Formatieren kann zu uneinheitlicher Darstellung führen
Wiki	(+) keine Installation für Benutzer nötig, Web-Browser genügt (+) hohe Akzeptanz bei Entwicklern (+) Verfolgen von Änderungen (Seitenhistorie) (+) gute Möglichkeiten zur verteilten Arbeit im Team (Kollaboration) (+) Inhalte leicht an alle Beteiligten zu kommunizieren	(-) offline arbeiten damit schwierig (-) für Abbildungen in der Regel weiteres Werkzeug erforderlich (ggf. Plugins) (-) in der Regel keine Versionen (nur Seitenhistorie, nicht über ganze Bereiche hinweg) (-) Wiki-Markup nicht für jeden Autor ideal (ggf. geringe Akzeptanz) (-) Formatierungsmöglichkeiten durch Wiki-Markup eingeschränkt
UML-Tool	(+) standardisierte, verbreitete Notation (+) gut geeignet für Abbildungen (+) konsistente Diagramme als Sichten auf das Architekturmodell (+) Verschiedene Dokumente aus einem Modell generierbar, auch zielgruppengerecht (+) Möglichkeiten des automatischen Abgleichs zwischen Modell und Implementierung (Reverse Engineering, „Roundtrip“-Engineering)	(-) In der Regel Auswahl und/oder Beschaffung des Tools erforderlich, mitunter hohe Kosten (-) Ausbildung/Einarbeitung nötig (-) Versionierung und Bearbeitung der Modelle im Team ggf. heikel (-) Für das Erstellen umfangreicher Textanteile (z.B. Konzepte) wenig geeignet (-) Umstieg von einem UML-Tool auf ein anderes birgt Risiken (Vendor Lockin)
Versions- verwaltung + txt	(+) einfacher Texteditor (oder die IDE) genügt zum Erstellen und Pflegen der Inhalte (+) Inhalte leicht gemeinsam mit dem Quelltext versionierbar, Änderungen sind leicht nachzuverfolgen (+) Potentiell Dokumentation in verschiedenen Ausgabeformaten möglich (HTML, PDF, ePub, ...) (+) Erzeugen der Dokumentation gut in den Build integrierbar (+) Form (und Formatierung) und Inhalt der Dokumentation gut voneinander zu trennen	(-) in der Regel kein WYSIWYG (abhängig von x und verwendetem Editor) (-) Skills zur Aufbau der Werkzeugkette erforderlich (-) für Abbildungen weiteres Werkzeug erforderlich (-) Je nach Format nicht für jedermann leicht zu editieren (ggf. geringe Akzeptanz) (-) Formatierungsmöglichkeiten beschränkt (z.B. bei «txt» = Markdown)

Anmerkung dazu: Die Vor- und Nachteile wiegen je nach konkretem Produkt oder «txt»-Format unterschiedlich schwer – im Einzelfall entfallen sie ganz oder es gibt akzeptable Workarounds. Gerade im Bereich der Wikis und UML-Produkte gibt es große Unterschiede – die Tabelle nennt für die Kategorien jeweils typische Argumente (bzw. Gegenargumente).

Alle Tools haben Stärken und Schwächen. Die meisten Projekte bedienen sich daher nicht eines einzelnen Werkzeugs, sondern einer Kombination. Beispielsweise ein UML-Werkzeug für die Diagramme, und ein Wiki für Textinhalte – die Abbildungen werden dann in die Wiki-Seiten eingebettet.

In letzter Zeit sehen wir vermehrt Werkzeugketten im Einsatz, die auf den Ansatz „Versionsverwaltung + «txt»“ setzen. Die Hauptmotivation dahinter ist, die Dokumentation nah an das Entwicklerteam zu bringen, und es dann in die Verantwortung zu nehmen, zumindest die grundlegenden Architekturansätze festzuhalten. Denn:

„Der Quelltext erzählt nicht die ganze Geschichte.“  (Simon Brown).

In folgenden Blog-Beiträgen nehmen wir die einzelnen Tool-Kategorien genauer unter die Lupe. Allen voran: „Versionsverwaltung + «txt»“. Welches Werkzeug ist Ihr Favorit?