XML-basierte Dokumentation in Software-Projekten

Präsentation zum Thema: "XML-basierte Dokumentation in Software-Projekten"—  Präsentation transkript:

1 XML-basierte Dokumentation in Software-Projekten
Vortrag zum BeLUG-Treffen vom Dieter Bremes,

2 Übersicht Ziele der Dokumentation Stand der Technik Praxisbericht DITA

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

4 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])

5 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)

6 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)

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

8 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)

9 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)

10 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)

11 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 Wochen) Project Velocity (Summe des geschätzen Aufwands aller Iteration fertig gestellte User Stories) (Acceptance tests)

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

13 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])

14 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)

15 Praxisbericht Ziele der XML-Dokumentation
Kontinuierliche Kommunikation Nachvollziehbarkeit Kosteneffizienz

16 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

17 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

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

19 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

20 Quellen eXtreme Programming
mingSummary whatisxp.htm SCRUM on/pages/50339.aspx scrum/index.php Software-Entwicklung generell Cockburn, Alistair: Writing Effective Use cases, ISBN Cockburn, Alistair: Agile Software Development 2nd Edition, ISBN ([COB1]) Cohn, Mike: Agile Estimating and Planning, ISBN Rothman, Johanna: Manage It!, ISBN ([ROT])

21 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

22 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

23 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?

24 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, ...

25 Quellen (DITA Open Toolkit: Werkzeuge, Dokumentation, Beispiele) dita (Vergleich DITA / DocBook, diverse Links) library/x-dita1/ (Introduction to the Darwin Information Typing Architecture) dita.com/Portals/0/dita/ditaguide.pdf (DITA for Solo Writers: Sehr gute Einführung) pics/ (5-minute DITA Tutorial)