Verbesserung und Pflege der Dokumentation der DPP-Software Saros

worked on by: Meike Johannsen

Outline

The documentation of the Saros project has become outdated and incomplete. This refers to the web page, which represents the project and will provide information both for users of the Eclipse-Plugin and the developers of Saros. On the other hand it concerns the comments in the source code. The aim of this work is to restructure the documentation to make it more clearly arranged and to develop a method for maintaining the documentation so that it will be updated and kept up to date.

Milestones and Planning

A milestone is a scheduled event signifying the completion of a major deliverable or a set of related deliverables. A milestone has zero duration and no effort -- there is no work associated with a milestone. It is a flag in the workplan to signify some other work has completed. Usually a milestone is used as a project checkpoint to validate how the project is progressing and revalidate work. (Source: http://www.mariosalexandrou.com/definition/milestone.asp)

Milestone no.	Past	CW	Goals	accomplished
1		18	Einarbeitung	accomplished
2		23	Recherche Dokumentation (Strukturierung/Aktuellhaltung)	accomplished
3		25	Strukturierungsplan aufstellen	accomplished
4		28-30	Dokumentationstruktur umsetzen	accomplished
5		33	Testen & Auswerten	accomplished
6		39	Schreiben	accomplished

Weekly Status

CW 11

Activities

• Einarbeitung
• BSE Antritts-Vortrag

CW 12-13

Activities

• Aufgaben des Testmanagers übernommen
• Recherche zu Strukturierung von Dokumentation (Internet & Bibliothek)
• Lesen von Technische Dokumentations Büchern
• Eindrücke gesammelt bei den Entwicklern
• Strukturierungs-Vorschlag für Webseite an die Saros-Mailingliste geschickt

Results

• Strukturierungs-Ideen in Recherche zusammengetragen

Next Steps

• weiter recherchieren
• Doxygen ansehen

Problems

• kein Feedback zum Strukturierungs-Vorschlag bekommen → nochmal nachgehakt

CW 14-15

Activities

• Doxygen installiert und ausprobiert
• Getting-Started Webseite wg. neuem Saros-View überarbeitet
• DA angemeldet

Next Steps

• über Fragen/Hypothesen zur Dokumention Gedanken machen

Problems

• Krank geworden

CW 16-17

Activities

• Fragen überlegt
• weiter Bücher gelesen
• nach Papern gesucht (IEEE Library, CiteSeer, …)

Next Steps

• Arbeitsplan verfeinern
• Bücher/Paper lesen
• Team befragen

Problems

• Messbarkeit der Fragen schwierig
• Recherche nicht all zu erfolgreich (→ Google Scholar)

CW 18-19

Activities

• Aufgaben des Assistent Test Managers übernommen
• Arbeitsplan verfeinert mit GANTT
• Recherche in Bibliothek und Internet (Google Scholar, MS Academic Search, …)
• Fragebogen ausgearbeitet und an die Saros-Mailingliste geschickt

Next Steps

• Bücher und Paper lesen
• bei Beantwortung des Fragebogens unterstützen Antworten zusammensammeln und erneut erinnern

CW 20-21

Activities

• Paper gelesen
• beim Fragebogen unterstützt (Fragen geklärt, teilweise persönliche Gespräche)
• Interview mit Christopher O. geführt
• Antworten zum Fragebogen zusammengetragen

Next Steps

• Fragebogen auswerten
• Treffen mit Stephan S. und Karl B. zur Architektur von Saros

Problems

• Paper sprechen existierende Probleme zur Dokumentation an, aber nicht, wie man dies verbessern kann
• Antworten auf Fragebogen teilweise nicht aussagekräftig

CW 22-23

Activities

• Besprechungen mit Stephan, Karl B. und Slawa

Results

• Strukturplan erstellt
• Testweise Struktur mit Doxygen umgesetzt
• High-level Architekturübersicht erarbeitet
• erstes svg-Architekturbild erstellt, welches mehrere Links enthalten kann

Problems

• Gruppierung des Treeview und Einbindung von externen Links bei Doxygen nicht möglich

CW 24-25

Activities

• Netzwerkschicht besprochen
• UI besprochen
• für Modulbeschreibungen Quelltext mit Kommentaren herangezogen
• Modulbeschreibungen mit Entwicklern nochmal durchgegangen/korrigiert

Results

• Kommentierungsregeln erstellt
• Invitation-Beschreibung erstellt

CW 26-27

Activities

• weitere Module besprochen (Concurrency Control, Eclipse Bridge, Shared Session, Utility)
• Plan für Dokumentationsmanager bzw. zur Erhaltung einer aktuellen Dokumentation erarbeitet

Results

• Modulbeschreibungen erstellt (Netzwerk, UI, Concurrency Control, Eclipse Bridge)
• Webseite umstrukturiert
• Modulbeschreibungen hinzugefügt
• Code Rules um Commenting Guidelines (Language & Documentation) erweitert

Problems

• SVG-Bilder brauchen im TWiki ein spezielles Plugin, welches nicht existiert → bei der Technik nachgefragt: durch einen künftige Umstellung zu Foswiki sind Plugin-Erweiterungen des TWiki nicht geplant - diese Plugin-Erweiterung wird geprüft

CW 28-29

Activities

• Kurzbeschreibung der Module des Saros high-level Bilds erstellt für die Technical Information Webseite
• Doxyfile konfiguriert für Quellcode-Dokumentation (Saros Javadoc)
• Anleitung zum Umgang mit fehlender, unvollständiger oder nicht aktueller Dokumentation erstellt
• Recherche bzgl. Prioritäten und Bug Trackern und Prioritäten für Documentation Issues festgelegt
• Listen mit Documentation Issues initialisiert als Start und Vorlage zum Erweitern
• Aufgaben des Dokumentations Managers zusammengestellt

Results

• Technical Information erweitert um Kurzbeschreibungen der Module inklusive Saros high-level Bild
• Documentation Issues (Anleitung zum Umgang und Listen) auf der Webseite eingebunden und vorgestellt
• Rolle des Dokumentationsmanagers eingeführt
• erste Javadoc Version verlinkt auf der Webseite

Next Steps

• Unterstüzten des Dokumentationsmangers in der Release Woche falls es Unklarheiten geben sollte
• package-infos erstellen

Problems

• in der älteren installierten Doxygen Version vom Server (1.6.3) funktionieren nicht alle Möglichkeiten, die ich in meiner Version (1.7.4) konfiguriert habe:
  • es gibt keine Auflistung der Pakete
  • eine Class Index Liste fehlt ebenso wie eine File List
  • es gibt anscheinend keinen Navigations Tree
  • insgesamt wird nicht ganz so viel Informationen aus dem Javadoc gezogen wie bei der neueren Version (das liegt aber u.U. auch an den Einstellungen)
• → auf der neu installierten Version ist alles ok

CW 30-31

Activities

• Aufgaben des Releasemanagers übernommen
• Dokumentationsmanager (Karl H.) in die neue Rolle eingeführt
• nach Issue-Tracking-Systemen (Bug Tracker) gesucht für die Documentation Issues
• Documenation Issues aus der TWiki-Tabelle in Sourceforge überführt
• Aufgaben des Dokumentationsmanagers sowie Documentation Issue Procedures überarbeitet

Results

• neuen Documentation Issue Tracker bei Sourceforge aufgesetzt
• package-infos für Pakete Concurrent, Jupiter, Management und Undo erstellt

CW 32-33

Activities

• mit dem Schreiben angefangen
• Saros Feature-Liste für die Webseite geschrieben

Results

• ein Plugin für SVG-Bilder im Twiki wurde doch installiert

Next Steps

• SVG-Graphiken bei den Modulbeschreibungen in die Webseite einbinden

CW 34-35

Activities

• Schreiben
• SVG-Graphiken auf der Webseite eingebunden

Results

• Navigation über die Links in der Architekturübersichts-Graphik möglich

CW 36-37

Activities

• zweiten Fragebogen erstellt, an die Saros-Mailingliste geschickt und im Softwareprojekt ausgeteilt

Results

• mehr Antworten in der zweiten Umfrage erhalten als in der ersten

Next Steps

• zweiten Umfrage auswerten

CW 38-39

Activities

• zweite Umfrage ausgewertet
• Aufgaben des Releasemanagers übernommen
• Dokumentationsmanager in seine Aufgaben eingeführt
• Schreiben

CW 40

Activities

• Ausarbeitung korrekturlesen und drucken