Dokumentation

In diesem Abschnitt wird die Dokumentation in den Unternehmen verglichen. Hierbei geht es sowohl um eine direkte Dokumentation der Architektur, wie auch um das Festhalten von Ent-scheidungen. Tabelle5.5stellt die unterschiedlichen Dokumentationsarten der Unternehmen gebündelt dar.

Unternehmen Inline Installation Ar chitekturmo

delle

Entscheidungen Weiter es

A X X Technical-Debt Tickets

Approaches und Proposals

B X X Fachliches Konzept

C X X Jour Fixe Protokoll

D X X X X Tests

E X X Kommentare an Stories

F X X X Slack-Archiv

G X X X Aufbau einer automatischen

Modellerzeu-gung

H X X X Todo-Board

Ø 8/8 8/8 3/8 2/8

Tabelle 5.5: Dokumentation

Grundsätzlich erstellen allen Teams eine inline Dokumentation. Hierbei werden meist einzelne Methoden, bzw. Zeilen beschrieben. Ein besseres Verständnis für die Architektur ermöglicht dies aber nicht. Sie unterstützen aber bei der Weiterentwicklung und der damit verbunde-nen Verwendung vorhandener Methoden. Interviewpartner E konnte von Beschreibungen berichten, die nicht mehr zur derzeitigen Funktionsweise gepasst haben. Wenn diese Fehlin-formationen liefern ist dies sehr problematisch. Eine andere Art von Dokumentation, die alle besuchten Unternehmen durchgeführt haben, ist eine Installationsanleitung. Diese dient zum Aufsetzten des Systems und hilft deshalb ebenfalls nicht besonders gut um zu verstehen wie die Anwendung aufgebaut ist.

Eine richtige Architekturdokumentation wird selten durchgeführt. Interviewpartner E konnte von verschiedenen Projekten berichten:„Meine Erfahrung ist, dass ist immer alles sehr schlecht.“

[E, 38:23min]. Der Interviewpartner A kann dies ebenfalls von seinem Projekt berichten:„Es ist aber nicht so, [...] dass wir eine Architekturdokumentation haben.“ [A, 48:14min]. G sagt, dass sie durch Pair Programming keine ausführliche Dokumentation benötigen: „Darüber verbreitet sich Wissen und deswegen brauchen wir auch keine Dokumentation über die interne Mikro-Architektur.“ [G, 17:08min]. Dies stimmt zu dem aktuellen Zeitpunkt,„aber wenn das jetzt Code ist, wo jemand das Projekt verlassen hat, dass versteht kein Mensch mehr“ [E, 42:04min].

Die Dokumentation sollte aber das Ziel haben auf lange Zeit verständlich zu sein.

In Unternehmen B wurde lange Zeit ein Architekturdiagramm manuell vom ursprünglichem CTO gepflegt. Inzwischen„hinkt [dieses] so ungefähr ein Jahr hinterher“ [B, 50:11min]. Mit dem Wechsel des CTOs wurde das Diagramm nicht weiter gepflegt.„Prinzipiell existiert dies eigentlich nur im Kopf weniger Leute.“ [B, 49:41min]. Dies sei „sehr problematisch, aus Sicht der Fachabteilungen. Da fehlt es definitiv an Verständnis der Gesamtarchitektur.“ [B, 50:43min].

Dies hatte einmal zur Folge, dass zwei Funktionalitäten gebaut wurde die sich gegenseitig ausgeschlossen haben. Es ist fraglich, ob die fachliche Produktentwicklung wirklich exakte Kenntnisse über die technische Architektur haben muss. Zum einen ist die Wahrscheinlichkeit, dass das notwendige technische Wissen vorhanden ist sehr gering. Zum anderen entsteht die Gefahr, dass dem Team von außerhalb technische Details vorgegeben werden. Bei D werden teilweise Architektur-Blueprints zur Dokumentation von Entscheidungen erstellt. Unterneh-men F pflegt ein vollständiges Diagramm der Architektur. Vor der Entwicklung malen die Entwickler meist händisch ihre Änderungen in das Diagramm. Anschließend werden diese in die digitale Version übertragen„Und wenn es eingebaut ist malen wir es nochmal schön auf.“[F, 21:11min]. Sie achten dabei sehr darauf, dass dies aktuell gehalten wird. Unternehmen G hat ebenfalls ein Modell der Makro-Architektur. Das Problem hierbei ist:„Das ist ein großes Netz, da sind viele Systeme drauf und viele Pfeile und so, was soll ich da jetzt raus lesen.“[G, 48:39min].

Durch die Größe ist das Diagramm sehr unübersichtlich und deshalb nicht besonders hilfreich.

Außerdem„ist das auch noch manuell gepflegt, das entspricht sowieso nicht der Wahrheit.“ [G, 26:44min]. Dadurch würden zum Teil vollständige Komponenten fehlen. Da alle Services bereits derzeit einen maschinenlesbaren Statusbericht zur Verfügung stellen, soll dieser mit hilfreichen Informationen (z.B. betreuendes Team, Abhängigkeiten, ...) angereichert werden. Hieraus soll automatisch ein Modell abgebildet werden.

Unternehmen H sagt, dass es viel wichtiger ist„die Entscheidungen und nicht die Bilder zu dokumentieren“ [H, 40:17min]. Dies ist wichtig, weil ein Diagramm nicht mehr aussage wes-halb sich etwas so entwickelt hat.„Das Optimum [...] ist, dass du zumindest zu jedem Checkin eine Referenz auf die Story eingibst.’[E, 39:03min]. Durch diese einfache Möglichkeit können bereits einzelne Entwicklungsabschnitte mit Stories in Verbindung gebracht werden. An der Story kann eventuell eine Diskussion stattgefunden haben. Diese kann aber auch helfen, um den passenden Ansprechpartner zu finden, sofern dieser noch im Unternehmen ist. Inter-viewpartner D sagt:„Tests sind z.B. auch wunderbare Dokumentationen.“ [D, 34:27min]. Die Tests können Informationen dazu liefern, wie etwas verwendet wird und was das erwarte-te Ergebnis ist. Gesprächspartnerin H kannerwarte-te dieses Argument, war aber skeptisch weil sie praktisch bisher nicht feststellen konnte, dass Tests zum Verständnis von Software eingesetzt

wurden. D erzählte:„Seit dem wir viel mit agilen Vorgehen unterwegs sind, dokumentiere ich mehr als vorher.“ [D, 29:08min]. Dies komme daher, dass Leute die Wert auf Qualität legen diese verwenden. Interviewpartner A sagt, dass bei ihnen die Proposals und Approaches als Entscheidungsdokumentation dienen könnten. Hierzu müsse aber an den dazugehörigen Ein-trägen eine Diskussion stattgefunden haben. Bei einer persönlichen Diskussion fehlt dies. Es ist wichtig die Gründe bei den Entscheidungsdiskussion zu notieren. Dadurch kann zu einem späterem Zeitpunkt evaluiert werden, ob dies noch aktuell ist:„Hat sich das geändert? Können wir jetzt mit ruhigem Gewissen eine andere Entscheidung treffen.“ [D, 31:11min]. E sagt, dass diese Art der Dokumentation meist nur zu Anfang eines Projektes stattfindet,„da sind noch alle motiviert, dann schreiben sie auch viel auf. Dann zwei Jahre später, guckst du rein und es hat sich nicht verändert“ [E, 40:56min]. Tragisch sei dies aber erst, wenn die Leute die dies umgesetzt haben nicht mehr im Team sind.

Diese Art von Dokumentation eignet sich nicht zum Einarbeiten neuer Mitarbeiter.„Das ist eine Dokumentation für Interne“ [D, 31:11min]. Gedacht ist sie stattdessen, um zu einem späterem Zeitpunkt Entscheidungen nachvollziehen zu können. In Unternehmen H werden gemeinsam getroffene Entscheidungen durch die Architekten per E-Mail verteilt. Die Entscheidungen stellen keine Richtlinien dar.„Es ist was flüchtiges, also es war in dem Moment wichtig, um dann festzustellen, dass man so weiter macht. Aber dann verfliegt es auch schon wieder.“ [H, 28:03min].

Dies bedeutet, dass es wichtig ist nicht auf früher festgelegte Entscheidungen zu beharren, sondern diese unter Umständen anzupassen oder vollständig zu verwerfen. Entscheidungen werden nur getroffen, um zu dem aktuellen Zeitpunkt in eine spezielle Richtung zu entwickeln.

Die Meinung von G stimmt hierzu überein:„Was nutzt es, wenn ich dann in die TD [(Technical Designer)] Runde reingehe und 12 Leute sagen mir, aber gucke mal, da haben wir es ja entschie-den. Ja, aber die Entscheidung war falsch.“ [G, 52:38min].

Ob eine Entscheidung oder das technische Konzept einer Realisierung dokumentiert wird, hängt größtenteils von dessen Umfang ab:„es muss so ein gewissen Maß an Größe haben.“ [B, 47,45min]. Auch bei D hängt das Ausmaß der Dokumentation sehr von der Größe, bzw. Komple-xität der Entscheidung ab. Die Ergebnisse werden häufig in einem Wiki festgehalten. Wie auch bei G:„Es gibt ein Wiki. Ich nenne es das Datengrab.“ [G, 51:28min]. In einigen Fällen werden hier Informationen hinterlegt.„Ich kenne nur niemanden der da rein guckt.“ [G, 51:58min]. Das Problem, dass eine Dokumentation ohne Sinn erzeugt wird, ist groß. Erst wenn Personen sie aktiv nutzen bleibt sie auf einem aktuellem Stand.„Wenn sie irgendwann nicht mehr genutzt wird, dann veraltet sie aber auch mit Recht.“ [D, 30:20min].

Die Technical-Debt Tickets von Unternehmen A sind ähnlich wie das Todo-Board von H.

Hier werden gefundene technische Schulden für eine spätere Beseitigung notiert. Dadurch

soll verhindert werden, dass diese in Vergessenheit geraten. Bei dieser Art von Ticket wird häufig eine Begründung für die Änderung notiert. Wenn diese, wie im Vorschlag von E, in der Commit-Nachricht verlinkt wird, kann die Begründung später nachgelesen werden. Bei Unternehmen B existiert vom Business Development ein fachliches Konzept welches direkt auf die Architektur einwirkt. Dieses kann ebenfalls als indirekte Dokumentation der Architektur betrachtet werden. Eine Aussage, wie gut eine Abbildung vom fachlichem Konzept auf die tatsächliche Implementierung stattfinden kann, kann hier nicht getroffen werden.

Das Treffen der Architekten wird in C mithilfe eines Jour Fixe Protokolls festgehalten. Hier wird über die gesamte überliegende Makro-Architektur geredet. Entscheidungen werden für alle zugänglich notiert und veröffentlicht.

Bei F wurde erzählt, dass viele der Diskussionen über das Chat System Slack stattfinden. Die Archive der alten Diskussionen können zum späteren Nachvollziehen genutzt werden. Die Gefahr bei solch einer Dokumentation ist, dass diese sehr unstrukturiert ist. Außerdem kann es vorkommen, dass sich auf Gespräche z.B. aus einem Meeting bezogen wird. Diese sind zu einem späteren Zeitpunkt nicht mehr nachvollziehbar.

Zusammenfassung

Eine Inline- und Installations-Dokumentation ist wichtig und hilft bei der Weiterentwicklung und dem Aufsetzen der Anwendung. Eine Übersicht über die Anwendung liefert dies aber nicht. Allgemein konnte kein Unternehmen sagen, dass ihre Dokumentation dazu genutzt werden kann, um sich in die Anwendung einzuarbeiten. Die Dokumentationen ist für Personen gedacht, die die Anwendung bereits kennen.

Allgemein ist schwer abzuschätzen, welches Maß an Dokumentation notwendig ist. Hier un-terscheiden sich die Firmen teilweise sehr. Die meisten führen keine oder nur eine geringe Dokumentation der Architektur durch. Ein manuelles gepflegtes Diagramm, welches von man-chen Unternehmen gepflegt wird, wird auf Dauer wahrscheinlich zu komplex und dadurch nicht mehr pflegbar. Häufig kann eine Art von Verlauf aus Chat-Protokollen, Meeting-Protokollen oder E-Mails herausgelesen werden. Wenn währenddessen zusätzliche mündliche Absprachen stattfanden gehen diese verloren. Sehr nützlich ist so etwas wie ein Todo-Board, um technische Schulden zu Dokumentieren. So gehen diese nicht verloren und können gezielt abgearbeitet werden.

Wichtig bei allen Dokumentationen ist, dass die Gründe für eine Entscheidung notiert werden.

Das reine Erzeugen von Diagrammen macht keinen Sinn, wenn die Begründung für die Art der Entwicklung nicht erfasst wird.