XML-basierte Dokumentation in Software-Projekten Vortrag zum BeLUG-Treffen vom 13.02.2008 Dieter Bremes, dbjobs@snafu.de

Übersicht Ziele der Dokumentation Stand der Technik Praxisbericht DITA

Ziele der Dokumentation Warum dokumentieren? Wenn Erstellungskosten < Kosten für erneute Beschaffung bzw. fehlende Information Wenn unumgänglich (Anford. des Kunden, des Gesetzgebers, ...)

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

Ziele der Dokumentation Wie dokumentieren? Kostenbewusst Zielgruppe berücksichtigen (kann 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)

Ziele der Dokumentation 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)

Ziele der Dokumentation Wer stellt welche Anforderungen? 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)

Ziele der Dokumentation Wer stellt welche Anforderungen? Nutzer braucht Informationen ... zur fachlichen Logik (= Soll-Zustand) zu Prioritäten / Zeitplan (= Soll-Zustand) über vorhandene / zu behebende Fehler (= Ist-zustand)

Ziele der Dokumentation Wer stellt welche Anforderungen? 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)

Stand der Technik eXtreme Programming (Schwerpunkt = direkte Kommun. im Team) User Stories auf Story-Cards, vom Kunden in Domänensprache ausgedrückt Release-Plan (Basis = User Stories, Laufzeit = Projektlaufzeit) Tasks auf Index-Cards, vom Programmierer in seiner Sprache ausgedrückt Iterationsplan (Basis = Tasks, Laufzeit 1 - 3 Wochen) Project Velocity (Summe des geschätzen Aufwands aller Iteration fertig gestellte User Stories) (Acceptance tests)

Stand der Technik SCRUM Product backlog Sprint backlog Burndown chart Task Board

Stand der Technik 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 Excel (Todo-Listen, Testpläne) führt zu Schreib-Sperren, hoher Formatierungsaufwand Word (Specs) zu unstrukturiert, Erfahrung / Talent zum Spec-Schreiben nötig, zuviel Arbeit UML sehr aufwändig XML-Kommentare / JavaDoc führen zu mechanischem Ausfüllen ohne Nachdenken = kein Informationsgehalt Wiki zu unstrukturiert (Befürchtung)

Praxisbericht Ziele der XML-Dokumentation Kontinuierliche Kommunikation Nachvollziehbarkeit Kosteneffizienz

Praxisbericht Übersicht der Dokumente (1 / 2) Admin.txt: DB-Setup, 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

Praxisbericht Übersicht der Dokumente (2 / 2) 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

Praxisbericht 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 ...)

Praxisbericht Details zu einzelnen Xml-Dokumenten AkteurZiel.xml Gut für 1. Überblick + 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

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

DITA Was ist DITA? (1 / 2) 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

DITA Was ist DITA? (2 / 2) 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

DITA Warum DITA? (1 / 2) Vorteile von XML, also standardisiert, versionierbar, strukturiert Bietet zusätzlich Grundstruktur (Topic und davon abgeleitet Concept, Reference, Task) Bietet zusätzlich Eigenschaften, z. B. zum Filtern (audience, status, rev; erweiterbar) Wiederverwendung von Informationen (Experten-Filter, Textbausteine) Infrastruktur vorhanden? Single Source Publishing?

DITA Warum DITA? (2 / 2) DITA-Dokumentation für Benutzer: Online-Hilfe Handbuch DITA-Dokumentation für Programmierer, Management, Kunde: Use Cases Design-Dokumente 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/DITATo pics/ (5-minute DITA Tutorial)