Projektdokumentation

Projektverzeichnis

Projektverzeichnis
Projektverzeichnis

Die folgende Projektstruktur verwende ich auf Basis des Vorschlags in IT-Projektmanagement kompakt (Pascal Mangold, Spektrum Akademischer Verlag Heidelberg, 2009).

  • Projektmanagement: Enthält alle Dokumente die zum Management gehören, dazu gehören Angebote, Kalkulation, Rechnungen und jede andere Korrespondenz mit Kunden oder Lieferanten.
  • Beistellungen: Hier landen alle Dokument und Dateien die von Dritten, einschließlich dem Kunden, beigestellt werden. Dazu zählen Normen, Software von Dritten usw.
  • Entwicklung: hier liegen alle Dokumente und Dateien die die (Software-)Entwicklung betreffen. Allgemeine Dokumente für den Anwender und über das System liegen hier. Pro Komponente oder Modul wird ein Unterverzeichnis angelegt in dem die Moduldokumentation und die Quelltexte liegen.
  • Lieferung: Hier landen alle an den Kunden gelieferten Pakete.

Dokumente mit zeitlichen Bezug wie Protokolle und Lieferungen, aber auch jede Beistellung werden mit dem Datum versehen, an Sie sie erhalten. Am einfachsten wird das Datum in der Form JJJJ-MM-TT als Dateipräfix vorangestellt. Die Reihenfolge Jahr, Monat, Tag mit führender Null sorgt für eine zeitiche Sortierung der Dateien im Dateimanager. Auf das Dateidatum des Dateisystem kann man sich nicht verlassen!

Architekturdokumentation

Die Vorlage Arc42, siehe Links, eignet sich meiner Meinung sehr gut für eine einfache, aber denoch weitreichende Dokumentation eines Systems. Unter Files unten finden sich Vorlagen für DocBook und Open Document. Für Word und diverse UML-Werkzeuge finden such auf der Webseite von Arc42 entsprechende Vorlagen.

Um in Präsentationen und Projektgesprächen den Stakeholdern Übersichten und Zusammenhänge darzubieten lohnt ein Blick auf Pecha Kucha, einer Vortragstechnik mit zwei einzuhaltenen Regeln: Der Vortrag besteht aus 20 Folien und für jede Folie stehen nur 20 Sekunden zu Verfügung. Eine Präsentation dauert damit nur 6[nbspMinuten und 40 Sekunden. MIt diesen Vorgaben wird man automatisch gezwungen, sich auf das wesentliche zu konzentrieren ;-)

Protokolle

Protokolle, vor allen von Besprechungen, sind schwierig, weil entwender fehlen sie oder sie sind da, aber unnütz. Nicht selten liest man dort, "XYZ hat die Teilnehmer begrüßt ...", "XYZ hat gesagt ...". Bei solchen Protokollen sollte man lieber auf das dokumententieren von Besprechungen verzichten. Interessant sind Aussagen wie "XYZ hat festgelegt ...", "XYZ muss die Aufgabe ABC bis zum DEF erledigen". Bemerken Sie den Unterschied? Letzteres sind konkrete Ergebnisse und nicht nur Mitschnitte. Ein Protokoll soll sich auf das wesentliche konzentrieren. Das ist gar nicht so einfach, wie es klingt.

Im Ergebnisprotokoll gibt es nur vier Arten von Einträgen:

  • Aufforderungen: sind konkrete Aufgaben die eine bestimmte Persion oder Gruppe bis zu einem festgelegten Termin erledigen muss.
  • Beschluss: ein gemeinsam getroffene Entscheidung für den weiteren Projektverlauf.
  • Empfehlung: eine unverbindliche Aufforderung an eine Person oder eine Gruppe.
  • Festellung: dient dem Festhalten von Fakten.

Aufforderungen und Beschlüsse sind verbindlich, sie können nur von Teilnehmern der Besprechung getroffen werden. Der Unterschied zwischen einer Aufforderungen und Empfehlung besteht auch darin, dass eine Aufforderung nicht an eine Partei gehen kann, der nicht an der Besprechung teilgenommen hat. Der Teamleiter kann natürlich seinem Teammitgleidern Aufgaben geben, auch wenn sie nicht teilgenommen haben. Einem Team(leiter) eine Aufgabe zu geben, ohne es zu vorher zu konsultieren ist jedoch unfair.

Eine Vorlage für ein Ergebnisprotokoll finden sie am Ende dieses Artikels.

Testdokumentation

Die beste Testdokumentation sind automatische Tests. Die Implementierung von Unit Test (z. B. mit JUnit) kann als solch eine Testdokumentation betrachtet werden. Dafür müssen nicht Seitenweise Testspezifikationen geschrieben werden.

Wird nach dem Test-First-Ansatz (auch Test Driven Development genannt) entwickelt, dann dokumentieren die Tests auch die Anforderungen an die zu testende Komponente. Wenn zuerst die Tests geschrieben werden und dann der Code, dann orientiert sich die Nutzund des Codes im Test an den Anforderungen. Setzt man dabei ein Code Coverage Tool (wie Emma bzw. JaCoCo für Java) ein, dann wird der Code nie mehr tun, als die Tests = Anforderungen verlangen. Andernfalls, würde die Code Coverage sinken. Insbesondere mögliche Ausnahmen und Fehlerfälle sollten beim Testen nicht vergessen werden!

Unit Tests sind von Natur aus sehr Code lastig und in der Regel ein Werkzeug des Softwareentwicklers. Für den Anwender oder Kunden, sind jedoch die Akzeptanztests wichtig, damit testet er nach seinen Regeln, ob die gelieferte Software nach seinen Wünschen funktioniert. Ein interessantes Tool ist Fit, das Framework for Integrated Tests. Damit kann der Anwender bzw. Kunde seine Test selber formulieren und gegen die gelieferte Software testen. Das funktioniert nach einen rechteinfachen Prinzip. Die Tests sind HTML-Tabellen, die sich leicht per Word, Excel oder OpenOffice bzw. Libre Ofice erstellen lassen. DIe Tabellen enthalten z. B. EIngangsdaten und erwartete Ausgangsdaten, können aber auch ganze Aktionsketten mit erwarteten Ergebnis darstellen. Zwischen den Tabellen darf beliebiger Freitext stehen, der beim Test ignoriert wird. Die Tabellen müssen einem einfachen Schema genügen.

Damit diese Tests ausführbar sind, muss natürlich auch hier ein Softwareentwickler ran. Nach man sich mit dem Anwender bzw. Kunden auf die zu testenden Funktionen geeinigt hat, müssen diese als Fixture mit Fit implementiert werden. Eine Methode in einem Fixture deligiert in den meisten Fällen einfach die angegeben Aktion in der HTML-Tabelle an das System under Test.

Zurück