Blog

Hoher Qualitätsanspruch ohne mentale Sandburgen und Dünkel - 10 Fragen an Ines Lasch

Ines Lasch macht eine Weiterbildung zur Technischen Redakteurin und absolviert ein achtwöchiges Praktikum bei parson. Wir haben ihr zehn Fragen gestellt. mehr ...

Volontariat für Technische Redakteure. Zwei Sichten auf die berufsbegleitende Ausbildung

Anja Schiel, Volontärin, und Ulrike Parson, Vorstand der parson AG, berichten über ihre Sicht des Volontariats für die Technische Redaktion.* mehr ...

Machen Sie Ihre technische Dokumentation intelligent – der Weg vom Content Management zu Content Delivery

In diesem Beitrag möchten wir Ihnen aufzeigen, wie man CDPs mit technischer Dokumentation so intelligent befüllt, dass die Nutzer schnell und gezielt Antworten auf ihre Fragestellungen bekommen. mehr ...

So funktioniert Mentoring bei parson

Die Bewerbung ist verschickt, das Vorstellungsgespräch war erfolgreich, jetzt kommt die Zusage. Und da ist er schon, der erste Arbeitstag, an dem alles so fremd ist: Kollegen, deren Namen man sofort wieder vergisst, Ablagestrukturen, Prozesse, ERP-System. Nicht mal die Kaffeemaschine funktioniert auf Anhieb. Und wo war noch mal der Besprechungsraum? mehr ...

Ein Jahr in London. Ich vermisse nicht nur meine Socke

Darf ich vorstellen? Parsons Green in London. Ich finde, der perfekte Ort für einen weiteren Standort von parson. Der Standort ist leider nicht geplant, aber ein Stückchen parson ist im Moment tatsächlich in London. 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