In der Welt der Softwareentwicklung ist die Dokumentation der Softwarearchitektur ein entscheidendes Element, das oft übersehen wird. Gute Dokumentation gewährleistet, dass alle Teammitglieder über das gleiche Verständnis der Softwarearchitektur verfügen, und ist daher von zentraler Bedeutung für die Effizienz und Qualität des Entwicklungsprozesses (Forward & Lethbridge, 2002) [1].

Inhaltsverzeichnis

Warum ist Softwaredokumentation wichtig?

Parnas (1985) [2] argumentiert, dass gut dokumentierte Softwarearchitekturen maßgeblich zur Wartbarkeit und Langlebigkeit von Software beitragen, die Produktivität erhöhen und die Kommunikation innerhalb des Entwicklungsteams verbessern. Eine gründliche Dokumentation erleichtert außerdem das Onboarding neuer Teammitglieder und verringert das Risiko eines Wissensverlusts, wenn erfahrene Mitarbeiter:innen das Unternehmen verlassen (Dingsøyr & Lassen, 2006) [3].

 

Grundlagen einer guten Softwarearchitektur-Dokumentation

Die Dokumentation der Softwarearchitektur sollte den folgenden grundlegenden Prinzipien folgen (Clements et al., 2010) [4]:

  • Klarheit:
    Die Dokumentation sollte klar und leicht verständlich sein, um Missverständnisse zu vermeiden.
  • Aktualität:
    Die Dokumentation sollte immer auf dem neuesten Stand der Software gehalten werden, um die Genauigkeit zu gewährleisten.
  • Vollständigkeit:
    Die Dokumentation sollte alle Aspekte der Softwarearchitektur abdecken.
  • Benutzerfreundlichkeit:
    Die Dokumentation sollte einfach zugänglich und nutzbar sein.
  • Richtigkeit:
    Die Dokumentation sollte korrekt sein und mit der aktuellen Version der Software übereinstimmen.

Falls dir die Normen DIN EN IEC/IEEE 82079-1: 2021/09oder ISO/IEC/IEEE 26514:2022-01 bekannt sind, werden dir die zuvor genannten Aspekte, auch als Qualitätskriterien für Technische Dokumentation oder Softwaredokumentation sehr bekannt vorkommen. In den beiden Normen sind diese Aspekte im Kern ebenfalls verankert.

 

Wie erstellt man eine herausragende Softwarearchitektur-Dokumentation?

Die Erstellung einer hervorragenden Softwarearchitektur-Dokumentation erfordert einen methodischen Ansatz und eine Verpflichtung zur Exzellenz. Hier sind einige konkrete Schritte, die du befolgen kannst:

1. Beginne mit der Planung

Überlege dir zuerst, was die Ziele deiner Dokumentation sind und wer sie lesen wird. Für Softwareentwickler:innen könnte das Ziel darin bestehen, die Funktionsweise des Codes zu erklären, während das Ziel für Projektmanager:innen darin bestehen könnte, den Projektfortschritt zu verfolgen. Deine Zielgruppe bestimmt die Sprache und den Detailgrad deiner Dokumentation.

 

2. Wähle dein Dokumentationsformat

Entscheide dich für ein Dokumentationsformat, das für dein Team am besten geeignet ist. Möglicherweise verwendest du eine Kombination aus UML-Diagrammen, Textbeschreibungen und Code-Kommentaren. Du kannst auch ein Dokumentationswerkzeug wie Doxygen, Sphinx oder Javadoc verwenden, um deine Dokumentation automatisch zu generieren oder zu formatieren.

3. Folge der Arc42-Vorlage

Die Arc42-Vorlage ist eine bewährte Methode zur Dokumentation von Softwarearchitekturen und beinhaltet alle wichtigen Aspekte, die in deiner Dokumentation enthalten sein sollten. Sie besteht aus 12 Abschnitten, darunter Einführung und Ziele, Randbedingungen, Kontextabgrenzung, Lösungsstrategie, Bausteinsicht, Laufzeitsicht und mehr. Jeder Abschnitt hilft dir dabei, einen bestimmten Aspekt deiner Softwarearchitektur zu dokumentieren und sicherzustellen, dass du keine wichtigen Details auslässt. (Starke G., 2008) [5]

 

4. Sei präzise und klar

Deine Dokumentation sollte präzise und klar sein. Vermeide zu technisch oder kompliziert zu sein, es sei denn, es ist absolut notwendig. So ermöglichst du auch neuen Teammitgliedern oder Entwickler:innen mit wenig Erfahrung, den Code besser zu verstehen.

 

5. Halte deine Dokumentation aktuell

Software verändert sich ständig, und deine Dokumentation sollte diese Veränderungen widerspiegeln. Plane regelmäßige Updates ein.

 

6. Verwende visuelle Hilfsmittel

Bilder und Diagramme können komplexe Konzepte vereinfachen und deine Dokumentation ansprechender machen. Nutze Diagramme, Schaubilder, Grafiken oder Illustrationen, um deine Softwarearchitektur besser zu veranschaulichen. Vor allem dann, wenn deine Zielgruppe zum großen Teil aus unerfahrenen Lesenden besteht.

 

7. Hole dir Feedback

Feedback ist ein wichtiger Teil der Dokumentation. Frage deine Kolleg:innen, ob sie deine Dokumentation verstehen und Verbesserungsvorschläge haben. Nutze hierfür Feedbackfragebögen, Umfragen oder technische Integrationen, die viele Wiki-Systeme bereits von Haus aus bieten, um Feedback oder Kommentare zu deinen Artikeln zu sammeln. Mit Tools wie z.B. Atlassian Confluence, kann dein Team auch innerhalb deiner Artikel zu einzelnen Abschnitten Artikel hinterlassen, Kommentare unter ganze Artikel setzen, deine Seiten liken oder mit Add-Ins auch gezielt Feedback abgeben. Zudem hast du in dem Tool mehrere Möglichkeiten, um z.B. die Beliebtheit einzelner Artikel auszuwerten und dir daraus Rückschlüsse abzuleiten.

 

8. Übe dich in Geduld

Gute Dokumentation ist ein kontinuierlicher Prozess, der Zeit und Übung erfordert. Sei geduldig und nimm dir die Zeit, die du brauchst, um eine Dokumentation zu erstellen, auf die du stolz sein kannst. Doch nicht nur das. Sei auch neugierig und proaktiv, denn in den wenigsten Fällen ist es so, dass dir neue Informationen oder Änderungen aktiv kommuniziert werden. Dies geht leider im Alltag zu oft unter. D.h., am aktuellsten ist deine Doku dann, wenn du aktiv nach neuer Information fragst. Bei vielen unserer Kund:innen, integrieren wir den Bereich der internen Softwaredokumentation in den Entwicklungsprozess mittels der bereits im Unternehmen existierenden Projektmanagementtools, wie z.B. Atlassian Jira. D.h. ein Sprint ist nicht Done, wenn ein bestimmter Dokumentationsumfang fehlt.

 

Fazit

Die Erstellung einer herausragenden Softwarearchitektur-Dokumentation ist kein leichtes Unterfangen, aber sie ist ein entscheidender Faktor für die Effizienz und Qualität der Softwareentwicklung. Wenn du das Gefühl hast, dass du Unterstützung bei der Erstellung oder Verbesserung deiner Software-Dokumentation oder der Integration der Softwaredokumentation in deine Entwicklungsprozesse benötigst, stehen wir bei STYRZ dir als Berater:innen zur Verfügung. Mit unserer umfangreichen Erfahrung in der Informations- und Softwareentwicklung können wir dir helfen, eine herausragende Dokumentation zu erstellen, die deinem Team zugutekommt und deine Software zum Erfolg führt.

 

Footnotes

  1. Forward, A., & Lethbridge, T. (2002). The relevance of software documentation, tools and technologies: a survey. Proceedings of the 2002 ACM symposium on Document engineering – DocEng ’02.
  2. Parnas, D.L. (1985). Software Aspects of Strategic Defense Systems. Communications of the ACM, 28(12), 1326-1335.
  3. Dingsøyr, T., & Lassen, K.B. (2006). Knowledge loss in software and system development: An exploratory case study. Information and Software Technology, 48(11), 995-1005.
  4. Clements, P., Bachmann, F., Bass, L., Garlan, D., Ivers, J., Little, R., … & Stafford, J. (2010). Documenting software architectures: views and beyond. Addison-Wesley Professional.
  5. Starke, G. (2018). Arc42 Template for Architecture Documentation. http://arc42.org/.