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

Blog

tekom-Jahrestagung 2018: Was gibt’s Neues bei iiRDS?

iiRDS war zentrales Thema auf der tekom-Tagung: das iiRDS-Café, Fachvorträge, Showcases und Tutorials widmeten sich dem neuen Standard. Auch auf Twitter wurde diskutiert, unter anderem über den für US-Kollegen so schwer auszusprechenden Namen. mehr ...

tekom-Bericht Teil 3: Kreativität statt Langeweile – Online-Videos für die technische Doku

Manege auf! Zu Beginn seines Workshops „Packende Online-Videos mit einfachen Mitteln erstellen“ zeigte Stephan Schneider zwei Bilder. mehr ...

tekom-Bericht Teil 2: Über echte und virtuelle Überflieger

Die tekom begrüßt mich mit strahlendem Sonnenschein. Drinnen sind Tagung und Messe bereits in vollem Gange. Zwei Tage Vorträge, Workshops, Messebesuch und Gespräche warten auf mich. mehr ...

tekom-Bericht Teil 1: Überwarnung ist real

Auf der tekom-Jahrestagung war das Informationsangebot zu Normen und Richtlinien groß. Unter anderem fanden sich Normungsexperten wie Jens-Uwe Heuer-James und Torsten Gruchmann zu einer Podiumsdiskussion zusammen, in der immer wieder anklang: Wir brauchen eine IEC 82079-1. mehr ...

Arbeiten in selbstführenden Teams. Oder wie wir das Management abschaffen

Die Welt von heute ist VUCA: volatile, uncertain, complex und ambiguous. Unternehmen stehen vor komplexen Herausforderungen wie Industrie 4.0 und dem Internet der Dinge. Wer nicht schnell genug agiert, wird vom Markt verdrängt. mehr ...
  • linkedin
  • xing