Top-Tools für Architekturdokumentation: Je fünf Stärken und Schwächen

By 20. Juli 2015Inhaltliches

Handyman_Tools_64
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_file_32.png Browser_32.png Package_cube_box_for_delivery_32.png TXT_file_symbol_32.png
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
WordWord_file_32 (+) 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
WikiBrowser_32.png (+) 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-ToolPackage_cube_box_for_delivery_32 (+) 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 + txtTXT_file_symbol_32 (+) 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?

3 Comments

  • Marco sagt:

    Beim Tooling gibt es leider öfters mal kleinere Religionskriege. Im Falle von Dokumentation tendiere ich deshalb eher in Richtung Text-basierter Formate. Dann kann man unter Umständen auch unterschiedliche Tools verwenden (ausser das Tool hat die Eigenschaft den Text umzuformatieren).

    Bei Word staune ich immer wieder wie wenig Ausbildung vorhanden ist (Ja, auch dieses Tool bräuchte Training). Würde man es nämlich richtig bedienen, wäre das mit der Formatierung auch keine Frage. Aber solange es Leute gibt welche Leerzeilen einfügen um zu formatieren wird das nichts.

    Und super dass du Sh…arepoint nicht erwähnst 🙂

    Mein aktueller Favorit ist AsciiDoc. Mit einem guten Tool hast du auch direkt einen Preview daneben. Ausserdem schätze ich dass man damit verschiedene Formate erzeugen kann (HTML, PDF, etc.).

  • Sven-Torben sagt:

    Wie ist denn deine Erfahrung mit analogen Tools wie z.B. Flipcharts?

    • Harm Gnoyke sagt:

      Moin Sven-Torben,

      meine Erfahrung mit Flipcharts oder Whiteboards ist, dass sie zur Diskussion (und dem Festhalten davon) am Besten geeignet sind.
      Für spätere Änderungen sind sie wiederum schlechter geeignet. Bei räumlich verteilten Teams kann man immer ein Foto machen, um das Ergebnis zu verteilen.
      Komplexe Sachverhalte lassen sich auf derlei Medien schwieriger festhalten. Das ist nicht unbedingt ein Nachteil, wenn man die Regel „Halte Deine Dokumentation schlank“ befolgt! Gerade für Überblicke habe ich es oft gesehen, dass man viel mit Flipcharts oder Whiteboards arbeitet.
      Aufpassen sollte man noch, wenn man viel damit arbeitet, weil man schnell Schwierigkeiten mit der Konsistenz bekommen kann.

      Was hast Du für Erfahrungen gesammelt?

Leave a Reply