XML-basierte Dokumentation in Software-Projekten
Der Vortrag beleuchtet zuerst die Gründe, Software überhaupt zu dokumentieren und analysiert kurz die Anforderungen, die von den verschiedenen Zielgruppen wie Programmierer, Kunden, Nutzern und Management gestellt werden.
Darauf folgt ein schneller Überblick der Dokumentation, wie sie die aktuelle Literatur etwa zu SCRUM oder aus der Pragmatic Programmers-Serie vorschlägt.
Danach erläutert ein Praxis-Bericht, welche teilweise überraschenden Erfahrungen beim Einsatz XML-basierter Dokumentation in einem Software-Projekt gemacht wurden.
Schließlich gibt der Vortrag noch einen kurzen Ausblick auf DITA (Darwin Information Typing Architecture). DITA ist eine Kreuzung zwischen DocBook und Wiki und insbesondere für stark strukturierte und vernetzte Inhalte geeignet, wie sie in der Dokumentation von Software-Projekten üblich sind.


Ziele der Dokumentation
Warum dokumentieren?
- Wenn Erstellungskosten niedriger als Kosten für erneute Informationsbeschaffung bzw. fehlende Information
- Wenn unumgänglich (Anforderung des Kunden, des Gesetzgebers, ...)

Was dokumentieren?
- Soll-Zustand (Anforderungen des Kunden, Zeitplan)
- Ist-Zustand (Fortschritt, aufgetauchte Fragen und Risiken, Ressourcenverbrauch)
- Informationen, die die Modellbildung unterstützen [COB, Seite 406], Bühne für den nächsten Auftritt vorbereiten [COB, Seite 220]

Wie dokumentieren?
- Kostenbewusst
- Zielgruppe berücksichtigen (kann der Kunde wirklich UML-Diagramme lesen?)
- Versioniert (wer hat wann was geändert, warum?)
- In standardisierten Dateiformaten (Infrastruktur und Wissen i. a. auch beim Kunden vorhanden, zukunftssicher)

Wer stellt welche Anforderungen?
- Programmierer braucht Informationen ...
  - zu Prioritäten / Zeitplan (= Soll-Zustand)
  - zur fachlichen Logik (Arbeitsablauf, Begriffsdefinitionen, ... = Soll-Zustand)
  - zu nicht-funktionalen Anforderungen (= Soll-Zustand)
  - über zu berücksichtigende Standards (Style-Guide, GUI-Richtlinien, ... = Soll-Zustand)
  - über vorhandene / zu behebende Fehler (= Ist-zustand)
  - über den Projektfortschritt (= Ist-zustand)
  - zur Modellbildung (als Kollege, Wartungsprogrammierer)
- Kunde braucht Informationen ...
  - zu Prioritäten / Zeitplan (= Soll-Zustand)
  - über den Projektfortschritt (= Ist-zustand)
  - über Projektrisiken (= Ist-zustand)
  - über zukünftige Administrationsaufgaben (Zusatz-Software, Patching, Lizenzen, ... = Soll-Zustand)
- Nutzer braucht Informationen ...
  - zur fachlichen Logik (= Soll-Zustand)
  - zu Prioritäten / Zeitplan (= Soll-Zustand)
  - über vorhandene / zu behebende Fehler (= Ist-zustand)
- Management braucht Informationen ...
  - zu Prioritäten / Zeitplan (= Soll-Zustand)
  - über den Projektfortschritt (= Ist-zustand)
  - über Projektrisiken (= Ist-zustand)


Stand der Technik
- Im Projekt
  - 200 seitiger Wunschzettel, Word = nicht versionierbar
  - Keine Fortschrittskontrolle (ständig 80 % fertig)
  - Keine Qualitätsmessung
  - (Keine systematische Verbesserung von Prozess oder Software)
- eXtreme Programming: 
  - (Schwerpunkt auf direkter Kommunikation innerhalb des Teams)
  - User Stories auf Story-Cards, vom Kunden in Domänensprache ausgedrückt
  - Release-Plan (Auf Basis der User Stories, Laufzeit = Projektlaufzeit)
  - Tasks auf Index-Cards, vom Programmierer in seiner Sprache ausgedrückt
  - Iterationsplan (auf Basis der Tasks, Laufzeit 1 - 3 Wochen)
  - Project Velocity (Summe des geschätzen Aufwands aller Iteration fertig gestellte User Stories)
  - (Acceptance tests)
- SCRUM:
  - Product backlog
  - Sprint backlog
  - Burndown chart
  - Task Board
- Pragmatic Programmer
  - Erfolgskriterien, Projekt-Prioritäten [ROT, Seite 8]
  - Velocity chart, Estimation quality chart, Requirements change chart [ROT, Seite 205]
  - Risk list, Release criteria [ROT, Seite 227]


Praxisbericht
Allgemeine Erfahrungen ohne XML-Doku
- Fehlerberichte u. ä. waren nicht XML-basiert = unstrukturiert + oft zu aufwändig
- Wiki zu unstrukturiert (Befürchtung)
- Excel führt zu Schreib-Sperren, hoher Formatierungsaufwand (Todo-Listen, Testpläne)
- Word zu unstrukturiert, Erfahrung / Talent zum Spec-Schreiben nötig, zuviel Arbeit
- UML sehr aufwändig

Ziele der XML-Dokumentation
- Kontinuierliche Kommunikation 
- Nachvollziehbarkeit
- Kosteneffizienz

Übersicht der Dokumente
- Admin.txt: Erstellen der DB aus Skripten, Konfiguration von Server und Anwendung (kein XML)
- AkteurZiel.xml: Kurzbeschreibung der Funktionen aus Benutzersicht, erste Informationssammlung (nach [COB1, S. 36])
- Design.txt: Kurzbeschreibung von Namenskonventionen, Lösungsmustern, ... (kein XML)
- Glossar.xml: Begriffsdefinitionen
- NichtFunktionaleAnforderungen.xml: Kurzbeschreibung von Anforderungen an Sicherheit, Performance, Datenschutz ...
- ReleasePlan.xml: Enthält Datum, Ziele und Kriterien der einzelnen Releases
- Risiken.xml: Beschreibung, Eintrittswahrscheinlichkeit, Gefahrenpotential, Prüfdatum, Abhilfe für jedes Risiko
- UC Xyz.xml: Use Case / Detaillierung eines Ziels mit Schritten und Resultaten für Normal- und Spezialfälle

Allgemeine Erfahrungen mit XML-Doku
- Wie erwartet sehr effizient (Einfachst-Struktur, kein Schema)
- Wie erwartet gut versionierbar
- Gemeinsame Website mit Editiermöglichkeit (Wiki, Schema?) oder spezialisierter Fat Client (XMLMind, InfoPath?) nötig
- Nutzerprobleme mit XML unterschätzt (sieht in Excel komisch aus ...)

Details zu einzelnen Xml-Dokumenten
- AkteurZiel.xml
  - Gut für 1. Überblick und unterstützt rollierende Planung [ROT, Seite 80]
- NichtFunktionaleAnforderungen.xml
  - Nützlich für Kunde- / Endkundengespräche (... haben Sie denn auch an Xyz gedacht?)
- Risiken.xml
  - Nützlich für eigene Priorisierung
- UC Xyz.xml
  - Dreh- und Angelpunkt der Informationssammlung und -kommunikation
- XML-Kommentare / JavaDoc
  - Führen zu mechanischem Ausfüllen ohne Nachdenken = kein Informationsgehalt

Quellen
- http://c2.com/cgi/wiki?ExtremeProgrammingSummary (eXtreme Programming)
- http://www.xprogramming.com/xpmag/whatisxp.htm (eXtreme Programming)
- http://codebetter.com/blogs/darrell.norton/pages/50339.aspx (SCRUM)
- http://www.mountaingoatsoftware.com/scrum/index.php (SCRUM)
- COB1 = Cockburn, Alistair: Writing Effective Use cases, ISBN 0-201-70225-8
- COB2 = Cockburn, Alistair: Agile Software Development 2nd Edition, ISBN 0-321-48275-1
- ROT = Rothman, Johanna: Manage It!, ISBN 0-9787392-4-8
- Cohn, Mike: Agile Estimating and Planning, ISBN 0-13-147941-5



DITA
Was ist DITA?
- Darwin Information Typing Architecture
- XML-basierte Infrastruktur zum Verwalten technischer (= stark strukturierter) Informationen 
- Grundkonzept:
  - Themenorientiert
  - Themen typisieren und spezialisieren
  - Inhalte wiederverwenden
  - Eigenschaften steuern Verarbeitung von Themen
- Besteht aus Regeln (DTDs, Schema), Tool-Chain optional (Open Toolkit: OSS-Beispiel-Implementierung mit Ant, XALAN, Java-Klassen, XSL)
- Kommerzielle Implementierungen z. B. in FrameMaker, XMetal, XMLSpy, ...
- Von IBM entwickelt, OASIS-Standard
- Im Einsatz u. a. bei Adobe, Boeing, IBM und Nokia

Warum DITA?
- Vorteile von XML, also standardisiert, versionierbar, strukturiert
- Bietet zusätzlich Grundstruktur (Topic und davon abgeleitet Concept, Reference, Task)###(Bild)
- Bietet zusätzlich Struktur für Referenzen (Inhalts- und Stichwortverzeichnis, Querverweise)
- Bietet zusätzlich Eigenschaften, z. B. zum Filtern (audience, status, rev; erweiterbar)
- Wiederverwendung von Informationen (Experten-Filter, Textbausteine)
- Infrastruktur vorhanden? 
- Single Source Publishing?
- DITA-Dokumentation für Benutzer: Online-Hilfe, Handbuch
- DITA-Dokumentation für Programmierer, Management, Kunde: Use Cases, Design
- Ohne DITA, weil einfach strukturiert: Akteur- / Ziel-Liste, Glossar, Release-Plan, Risiko-Liste, Liste nicht-funktionaler Anforderungen,

Quellen
- http://sourceforge.net/projects/dita-ot/ (DITA Open Toolkit: Werkzeuge, Dokumentation, Beispiele)
- http://times.usefulinc.com/2006/01/23-dita (Vergleich DITA / DocBook, diverse Links)
- http://www.ibm.com/developerworks/xml/library/x-dita1/ (Introduction to the Darwin Information Typing Architecture)
- http://www.lone-dita.com/Portals/0/dita/ditaguide.pdf (DITA for Solo Writers: Sehr gute Einführung)
- http://www.ditausers.org/training/DITATopics/ (5-minute DITA Tutorial)

Extras
Allgemeine Erfahrungen mit Projekt 
- Hauptproblem: für alle Beteiligten ein Nebenbei-Projekt, Aufwand weit unterschätzt
- Abschätzung und Time-Boxing fehlten
- Dokumentation oft erst spät aktualisiert
- Erst spät festgenagelt (Priorisierung / Detailplanung / offizielle Todo-Liste fehlte)
- Sehr gute fachliche Spezifikation (Dienstvorschrift)
- Besprechungsprotokolle für Remote-Arbeiten nötig, auch aus Kundensicht


Offen