Blog

How to become a technical writer – Confessions of a former translator

A former translator, I worked the first seven years of my professional life in the translation industry, in various positions. While I learned a lot from this experience, it also left me, as a writer, frustrated. Translators are chained to their source text and writing the words of others in another language, usually focusing on what their clients want. mehr ...

tekom-Impressionen Teil 2: API-Dokumentation und die VUKA-Welt

Daniela Herbold und Ulrike Parson berichten über Leitlinien für eine optimierte API-Dokumentation sowie Lösungsansätze für eine innovative Personalführung. mehr ...

tekom-Impressionen Teil 1: Improvisationstechniken, Fluff Hunt und Videos

Auf dem Weg zur Konferenz sehe ich an der Fassade des Stuttgarter Bahnhofs ein Zitat von Hegel: „daß diese Furcht zu irren schon der Irrtum selbst ist“. Genau darum ging es in Anthonys Apodacas Vortrag am Morgen des zweiten Konferenztages. mehr ...

My first time at tekom

I got back from Stuttgart last night and it is safe to say that after three days of action-packed presentations, writing an article is not in the realm of possibilities right now as I try to connect one synapse with another. mehr ...

Eine Tasse auf Reisen #4 - die Auflösung

In welcher Stadt wurde die parson-Tasse fotografiert, haben wir Anfang September gefragt. Die Frage war knifflig. Trotzdem kamen die meisten auf die richtige Antwort: In Chicago, USA. mehr ...

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


  • facebook
  • linkedin
  • xing