5 Hürden, die Sie in Doku-Vorhaben meistern

Hürdenlauf

Heute geht es um die typischen Hürden, die einem Softwareteam begegnen, wenn ein Vorhaben zur Dokumentation von Softwarearchitektur gestartet werden soll. Oft kommen solche Hürden schleichend auf Sie zu, und Sie merken nicht einmal, wenn Sie hineinlaufen und dadurch zurückgehalten werden.

Also lassen Sie uns einen Schritt Abstand nehmen und sehen, welche von diesen hier Sie im Moment zurückhält:

Hürde 1: Doku kostet Zeit und Aufwand

Menschen scheuen den Aufwand, den gute Doku kostet, in der Erstellung, in der Pflege und in der Kommunikation. Deshalb wird Doku oft gar nicht erst begonnen oder auf halber Strecke wieder abgebrochen.

Der Nutzen der Doku wird dabei gar nicht betrachtet, nämlich die 6 dicken Vorteile von Doku, die Sie aus meiner Anleitung Architekturdokumentation kennen.

Die fehlende Nutzenbetrachtung hält Architekten und deren Vorgesetzte zurück, in Doku zu investieren.

Hürde 2: Unklare Zuständigkeit

In vielen Teams ist nicht klar, wer die Doku schreiben soll. Oft wird eine einzelne Person dazu verdonnert, die dann hoffnungslos überfordert ist.

Teilen Sie stattdessen die Doku-Arbeit im ganzen Team auf, sogar inklusive Stakeholder. Eine einzelne Person braucht dann die Ergebnisse nur noch zusammenzuführen und konsistent und widerspruchsfrei zu machen.

Wenn ein Doku-Kümmerer fehlt, hält dies Teams davon ab, zu guter Doku zu gelangen.

Hürde 3: Zu geringer Nutzen

Oft wird Doku geschrieben, die keinen Nutzen hat. Wenn die Doku zum Beispiel durch ein rigides Vorgehensmodell mit riesigen Templates bestimmt wird, entstehen große Dokumente, die weder die Architekten beim Entwurf der Architektur unterstützen noch die Entwicklern bei der Umsetzung.

Zusammen mit Hürde 1 (hoher Aufwand) bringt dies Unternehmen dazu, Doku wieder einschlafen zu lassen. Halten Sie also die Doku schlank. Bringen Sie nur das ein, was mindestens einem Typ von Stakeholder (z.B. den Entwicklern) nützt.

Hürde 4: Fehler in der Doku

Vielfach ist die Doku, die entstanden ist, veraltet, enthält mittlerweile falsche Aussagen, ist inkonsistent oder widersprüchlich. Wer kennt das nicht: Man benennt im Code eine Komponente um und im Text des Dokumentes auch, doch man vergisst, auch die zugehörigen Diagramme zu ändern, in denen die Komponente vorkommt.

Für die Leser solcher Doku führt das zu Rückfragen und Zeitaufwand. Noch ein Grund, warum Architekten sich scheuen, zu dokumentieren. Behandeln Sie Fehler in der Doku genauso wie Fehler in der Software: Testen, entdecken, aufnehmen, beseitigen.

Hürde 5: Multi-User-Konflikte beim Erstellen

Wenn Architekten mit anderen Menschen gemeinsam Doku erstellen, kommt es manchmal zum Überschreiben eines Doku-Standes durch einen anderen, weil nicht klar ist, wer gerade an welcher Version arbeitet und welches eigentlich der aktuelle Stand ist.

Verschärft wird diese Hürde, wenn veraltete UML-Tools im Einsatz sind, die das Thema Versionsverwaltung gar nicht oder nur unzureichend unterstützen.

Doku-Vorhaben werden unter solchen Umständen ebenfalls nach ein paar Versuchen wieder eingestellt.

Wie Sie die Hürden auflösen

 width=

7-Schritte-Anleitung für ArchitekturDoku

In meiner Anleitung, die Sie sich sicherlich schon heruntergeladen haben, hatte ich 7 Schritte aufgezeigt, die Sie gehen sollten, um zu guter Doku zu kommen:

  1. Den Kümmerer finden
  2. Zielgruppen identifizieren
  3. Inhalte pro Zielgruppe festlegen
  4. Medien ziegruppengerecht festlegen
  5. Planen auf Teamarbeit hin
  6. Erstellen, ablegen, compilieren
  7. Feedback holen und einpflegen

Mit diesen 7 Schritten lösen Sie die Hürden auf.

Doch für jedes Unternehmen bedeuten diese Schritte etwas anderes. Die Umgebungen sind verschieden, die Menschen, die Tools, die Prozesse.

Sie können für Ihr eigenes Unternehmen selbst herausfinden, wie diese Schritte bei Ihnen und für Ihre Leute aussehen müssen. Das kann dauern.

Oder: Sie nehmen einfach eine Abkürzung!

In nur 2 Tagen die Hürden zu guter ArchitekturDoku überwinden

Click To Tweet

Eine Abkürzung, die ich für Sie vorbereitet habe, weil ich will, dass Sie schneller und erfolgreicher vorankommen: Mein 2-tägiger Workshop “Softwarearchitektur dokumentieren”.

In nur 2 Tagen lernen Sie, Softwarearchitektur angemessen zu dokumentieren, so dass Ihr Publikum die Doku gern liest und Sie selbst als Autoren wenig Wartungsaufwand damit haben.

Sie möchten ja, dass Ihre Doku von unterschiedlichen Stakeholdern verstanden und geschätzt wird. Dass die Entwickler die Lösung richtig umsetzen. Und dass Ihre Entwurfsentscheidungen sicher eingehalten werden. Die Techniken dazu lernen Sie in meinem Workshop!

Klicken Sie hier auf die Anmeldeseite des Workshops. Dort finden Sie alles über den Inhalt, die Voraussetzungen, Termin und Ort, Durchführungshinweise und auch gleich das Anmeldeformular.

Ich freue mich, Sie im Workshop zu begrüßen und mit Ihnen gemeinsam dort zu lernen und zu üben.