Blog

Flipped Classroom: Schulungen effizienter gestalten

Es kostet nicht nur Zeit, in einer Präsenzschulung auf die häufig sehr unterschiedlichen Kenntnisse der Teilnehmer einzugehen. Auch besteht die Gefahr, dass sich Teilnehmer mit höheren Vorkenntnissen langweilen, während sich diejenigen mit geringem Vorwissen überfordert fühlen. mehr ...

Is DITA working for you? Ergebnisse vom DITA Satisfaction Survey 2017

Technische Redakteure aus 250 Unternehmen weltweit haben bereits an der Umfrage des Content Wrangler’s 2017 teilgenommen. Jetzt sind die ersten Ergebnisse da. mehr ...

Der Kern intelligenter Informationen: die Metadaten

In dem schicken neuen Blog der tekom dreht sich alles um Intelligente Informationen. Der Blog will Fachleute aus verwandten Bereichen zusammenbringen, um die verschiedenen Aspekte des Designs und der Entwicklung intelligenter Technologien zu erforschen und zu vernetzen. mehr ...

Eine Tasse auf Reisen #3 - die Auflösung

Vor welchem Gebäude wurde die parson-Tasse fotografiert, haben wir Anfang Juni gefragt. Die Frage war knifflig. Trotzdem kamen die meisten auf die richtige Antwort: vor dem Himmelstempel in Peking. mehr ...

Gewinnspiel: Eine Tasse auf Reisen #3

Die parson-Tasse hat wieder fleißig Meilen gesammelt! Wohin es den "Abenteurer" diesmal verschlagen hat, erkennen Sie vielleicht nicht auf den ersten Blick, mithilfe unserer Tipps aber ganz bestimmt. 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