Software-Dokumentation im Open Space der seacon 2013

Letzte Woche besuchte ich die seacon 2013, die Konferenz für Softwareentwicklung im Norden Deutschlands. Neben vielen hervorragenden Fachvorträgen und Pecha Kucha gab es auch wieder 2 Slots für Open-Space-Diskussionen. Die Themen dafür schlugen die Teilnehmer am ersten Tag der Konferenz vor. Ich nahm allen Mut zusammen und schlug als Thema für einen der Slots Technische Dokumentation vor, genauer gesagt „Wieviel Dokumentation braucht man in agilen Projekten?"

Meine anfänglichen Befürchtungen erwiesen sich als unbegründet. Nicht nur kamen etliche Teilnehmer zu dem Open Space. Wir hatten auch eine lebhafte Diskussion mit sehenswerten Ergebnissen.

Hier in Kürze die wichtigsten Erkenntnisse und Erfahrungen:

Welche Arten von Software-Dokumentation schreibt ihr?

  1. Testdokumentation: Tests beschreiben sehr gut, welches Verhalten von der Software erwartet wird. Szenarien bilden beim Behavior Driven Development die Grundlage für automatisierte Tests. Außerdem stellen sie bereits eine aussagekräftige Dokumentation dar.
  2. Anforderungsspezifikation, z.B. in Form von User-Stories
  3. Architekturdokumentation
    • Am wichtigsten ist es, die Designentscheidungen zu dokumentieren, um später wieder darauf zurückgreifen zu können. Warum haben wir diesen Algorithmus gewählt, warum haben wir das so implementiert? Dies kann man z.B. mit minimalem Aufwand in einem Wiki machen.
    • Die manuelle Pflege und Aktualisierung von Modellen und UML-Diagrammen ist sehr aufwändig. Wo möglich, sollten Diagramme automatisch erzeugt werden, z.B. Klassendiagramme.
    • arc42 ist bekannt, aber oft wird nicht in diesem Umfang dokumentiert
  4. Source-Code-Kommentare. Hier gingen die Meinungen stark auseinander. Einige vertraten die Ansicht, dass durch eine sprechende Benennung und Namenskonventionen die Funktion von Klassen und Methoden ohne weitere Kommentare klar werden sollte. Andere hielten
    Code-Kommentare für sinnvoll. Einig waren sich alle darüber:
    • Sprachliche Konventionen festlegen und einhalten, um einheitliche und sprechende Benennungen zu erhalten. Benennungen mit Domänensprache abgleichen.
    • Externe APIs müssen dokumentiert werden, d.h. in der Regel auch in Form von Code-Kommentaren
    • Source-Code-Kommentare nur dort einsetzen, wo notwendig (minimalistischer Ansatz)
  5. Benutzerdokumentation
    • Benutzerdokumentation muss auf den Aufgaben der Benutzer basieren, deshalb bilden User-Stories eine hervorragende Grundlage für Handbücher.
    • Technische Redakteure schreiben Benutzer-, Admin- und auch Entwicklerdokumentation und sollten Teil des interdisziplinären Scrum-Teams sein. Sie können u.a. die Terminologie im Projekt festlegen sowie Benennungen und Strukturen vereinheitlichen

Wann schreibt ihr Dokumentation?

  • Dokumentation muss laufend im Projekt geschrieben und gepflegt werden
  • Dokumentation muss in die Definition of Done aufgenommen werden, um Teil des Entwicklungsprozesses zu werden
  • Zum Ende des Projekts sollte der Dokumentationsstand dem Entwicklungsstand angepasst werden

Wie schreibt ihr Dokumentation und mit welchen Tools?

  • Dokumentation muss zielgruppengerecht sein, d.h. speziell zugeschnitten für Entwickler, Tester oder Endbenutzer >> Inhalte und Form entsprechend auswählen
  • Dokumentation muss minimalistisch sein
  • Dokumentation macht nur Sinn, wenn sie qualitativ hochwertig und aktuell ist. Dokumentation stellt einen Wert dar.
  • Einige nutzen Wikis für Architekturdokumentation und Szenarien, z.B. MediaWiki, Semantic MediaWiki und Confluence. Häufig können Diagramme nicht direkt in Wikis eingebunden werden, sondern müssen in anderen Tools erstellt und dann als Bild (PNG etc.) ins Wiki geholt werden. Die beiden Versionen (Quelle und Wiki) können dadurch auseinanderlaufen. Eine mögliche Lösung: Mit Signavio kann man BPMN-Diagramme u.a. in Confluence einbetten.
  • Andere benutzen ausschließlich UML-Tools, um alle Informationen in einer Quelle zu haben.

SeaconOpenSpace

Kommentar schreiben


Blog

Über Lampen, Birnen und Fluchtinstinkte. Nachschlag zur tekom-Tagung 2019

Im letzten Teil unserer tekom-Nachlese gehts um Erleuchtungen in einem Terminologieworkshop und Fehlermeldungen, die den Fluchtinstinkt in uns wecken. mehr ...

KI als Chance oder Bedrohung für den Technischen Redakteur? Bericht von der tekom-Tagung, 3. Teil

Der Begriff Künstliche Intelligenz (KI) ist ein Phantom. Jeder Mensch assoziiert sofort etwas damit, doch die Vorstellungen sind selten deckungsgleich. mehr ...

Sprung ins kalte Wasser oder wie ich das erstmal Mal slammte. Bericht von der tekom-Tagung, 2. Teil

Eigentlich bin ich ja ein alter Hase bei der tekom-Tagung und sollte nicht mehr allzu aufgeregt sein, wenn ich einen Vortrag halte. Aber als Dieter Gust und ich unsere Feierabend-Schnapsidee einer scherzhaften Debatte (Trend-Slam) auf die Bühne brachten, war mir doch etwas flau im Magen. Wie würde das wohl ankommen? mehr ...

Der-die-das, drei Redakteure gehen essen und ein Könjunktiv. Bericht von der tekom-Tagung, 1. Teil

Eine Referentin irritierte mich, weil sie konsequent von "dem" Engine sprach, der in der Software für die maschinelle Übersetzung zuständig ist. Ich benutze bei Engine immer "die".  mehr ...

Der iiBot gibt Anweisung

Ein Chatbot, der dem Servicetechniker genaue Anweisungen für seine akute Fragestellung gibt – live, anwendungsgerecht und zugeschnitten auf die Qualifikation des Servicetechnikers. mehr ...
  • linkedin
  • xing