In vielen der Beispiel-Projektdokumentationen auf dieser Seite werden Artefakte im Anhang der Projektdokumentation nicht vollständig, sondern nur als Auszug bzw. als Teil angefügt. Den Sinn dahinter möchte ich in diesem Artikel erklären, da ich bereits mehrfach darauf angesprochen wurde, ob das so üblich sei.
Die kurze Antwort: Es geht darum, den wenigen verfügbaren Platz in der Projektdokumentation bestmöglich auszunutzen.
Was gehört in den Anhang der Projektdokumentation?
Im Anhang der Projektdokumentation sollte man grundsätzlich die Informationen anfügen, die nötig sind, um das Projekt zu verstehen bzw. die fachliche und technische Kompetenz des Prüflings bewerten zu können. Alle Artefakte müssen dabei im Fließtext referenziert werden und diesen sinnvoll ergänzen. Alleinstehende Artefakte ohne Bezug zum Text gehen genauso wenig wie ein Text, der nur aus Referenzen auf den Anhang besteht. Als Daumenregel gilt dabei: Alles was größer als eine halbe Seite ist, gehört in den Anhang und nicht in den Fließtext. Lange Tabellen und Abbildungen ziehe ich z.B. bei der Bewertung von Dokumentationen von der Anzahl der Seiten ab, um auf den „Nettotext“ zu kommen.
Nehmen wir mal ein konkretes Beispiel: Das Ergebnis der Analysephase eines Projekts lässt sich sehr gut in Form eines Lastenhefts darstellen. In vielen Projekten wird mit diesem Artefakt gearbeitet und es markiert das Ende der Ist-Aufnahme. Analog könnte ein Pflichtenheft dazu dienen, die Entwurfsphase zu dokumentieren. Vergleichbare Artefakte aus den anderen Phasen üblicher Projekte wären z.B.:
- Use-Case-Diagramm (Entwurfsphase)
- Entity-Relationship-Modell oder Tabellenmodell (Entwurfsphase)
- Klassendiagramm (Implementierungsphase bzw. Entwurfsphase, je nach Einsatzzweck)
- Ereignisgesteuerte Prozesskette (Ist-Analyse oder Entwurfsphase)
- Testspezifikation (Implementierung oder Entwurf)
- Quelltextbeispiele (Implementierung)
- Screenshots der Anwendung (Implementierung)
- Benutzerdokumentation oder Entwicklerdokumentation (Dokumentation)
Diese Artefakte gehören meiner Meinung nach in jede Projektdokumentation! Natürlich nur, wenn sie sinnvoll sind. Für eine prozedurale Programmierung wird man wohl kaum ein Klassendiagramm erstellen, sondern eher Ablaufdiagramme.
Zeige nur spannende Inhalte!
Viele IHKen machen konkrete Vorgaben, wenn es um die Seitenzahl der Projektdokumentation und insb. des Anhangs geht. Bei der IHK Oldenburg ist z.B. der Fließtext auf 15 Seiten beschränkt und der Anhang auf 25 Seiten. Das heißt, der Prüfling muss genau entscheiden, welche Artefakte er in die Projektdokumentation packt. Und hier wäre es meiner Meinung nach wichtig, das volle Spektrum der Projektarbeit zu zeigen. Wenn nun z.B. ein Lastenheft mit Deckblatt, Inhaltsverzeichnis, Tabellenverzeichnis und den eigentlichen Inhalten (den aufgenommenen Anforderungen) mehrere Seiten umfasst, ist es nicht sinnvoll, dieses komplett in die Projektdokumentation einzubauen.
Der verfügbare Platz, der hierbei für andere interessante Artefakte verloren geht, wird mit für den Prüfer völlig uninteressanten Dingen aufgefüllt. Ich glaube jedem Prüfling, dass er ein Inhaltsverzeichnis für ein Lastenheft erstellen und auch ein nettes Deckblatt gestalten kann. Das muss ich nicht vollständig im Anhang einer Projektdokumentation sehen, weil es mir keinerlei Mehrwert für die Bewertung bietet. Viel wichtiger sind doch die fachlichen Inhalte, also z.B. die aufgenommenen Anforderungen als User Stories oder als priorisierte Liste („muss“, „soll“, „kann“ usw.). Das ist ein wichtiger Teil der Projektarbeit und muss demonstriert werden. Das obligatorische Geplänkel drumherum interessiert mich nicht. Genauso verhält es sich mit seitenlangen Quelltextauszügen. Mich interessieren nicht die langweiligen Klassendefinitionen oder Getter- und Setter-Methoden, sondern spannende selbst entwickelte Algorithmen.
Was sind die spannenden Inhalte?
Wichtig ist natürlich, dass die Artefakte trotz Kürzung verständlich bleiben. Komm also nicht auf die Idee und streiche zentrale Klassen aus dem Klassendiagramm oder Entitäten aus dem ERM, nur um weniger Inhalt zu haben. Das Artefakt muss auf die Kernaussage reduziert werden, die deine eigene Leistung darstellt! Es folgen einige Beispiele.
- Lastenheft: priorisierte Anforderungen und nicht Deckblatt, Inhaltsverzeichnis oder Änderungshistorie
- Pflichtenheft: zentrale Entwurfsentscheidungen (z.B. Programmiersprache, Architektur, Frameworks) und nicht das Drumherum wie beim Lastenheft
- ERM, Tabellenmodell, Klassendiagramm: die eigenen Inhalte (Klassen, Entitäten) und nicht bereits vorhandene, die du wiederverwendest
- Quelltext: selbst entwickelte Algorithmen und nicht „Boilerplate“-Code wie Klassenrümpfe, Getter/Setter und Framework-spezifische Inhalte
- Benutzerdokumentation: Beschreibung zentraler Use-Cases und nicht allgemeines Blabla oder Deckblatt usw.
- Entwicklerdokumentation: Beispiele von umfangreichen, zentralen Klassen und nicht von simplen Datenobjekten (z.B.
getName(): Returns the name.) - Kostenkalkulation: Gesamtkosten und Amortisationsrechnung für das Projekt auf Basis vorgegebener Kostensätze statt „Kalkulation“ des eigenen Stundensatzes (das kann euer Rechnungswesen besser als du)
Zeige deinen vollen Leistungsumfang!
Lastenheft und Quelltext sind jeweils nur ein Artefakt einer bestimmten Projektphase. Werden diese Artefakte zu lang dargestellt, fehlt der Platz für die anderen Projektphasen, die genauso wichtig sind oder sogar noch wichtiger. Als Prüfer möchte ich sehen, dass der Prüfling alle möglichen Bereiche der Projektarbeit angemessen bearbeitet und dokumentiert hat. Und große Artefakte einer einzelnen Projektphase, die zu viel Platz einnehmen, verhindern das. Oft fehlen in Projektdokumentationen komplette Phasen! Da wird z.B. nicht eine einzige Zeile Quelltext gezeigt oder die fertige Anwendung ist nicht abgebildet.
Normalerweise sollte man als Prüfling kein Problem damit haben, die vorgegebene Seitenzahl zu erreichen. Meist hat man mehr als genug Inhalte, um die Seiten zu füllen. Also muss man zwangsläufig eine Kürzung vornehmen, um seine gesamte Leistung zeigen zu können. Hier ist auch der Prüfling gefragt, zu entscheiden, welche Inhalte denn nun eigentlich wichtig sind. Das ist quasi ein wichtiger Prüfungsbestandteil: Die Unterscheidung von wichtigen und unwichtigen Bestandteilen. Und ein Deckblatt eines Lastenheftes, das eine gesamte Seite im Anhang raubt, ist sicherlich nicht wichtig. Stattdessen könnte man zusätzliche Diagramme oder andere Inhalte platzieren. Daher enthalten die mit 100% bewerteten Beispieldokumentationen auch fast immer nur Auszüge aus größeren Artefakten, dafür aber eine Vielzahl unterschiedlicher Artefakte.
Übrigens: Falls du unter der vorgegebenen Seitenzahl bleibst, erkläre ich hier, warum das keine gute Idee ist: Sinnvolle Anzahl der Seiten der Projektdokumentation.
Halte dich an die Vorgaben deiner IHK!
Ich habe gehört, dass einige IHKen auch komplette Artefakte im Anhang erwarten. In den Handreichungen steht dann z.B., dass Lasten- und Pflichtenheft in vollem Umfang anzuhängen sind. Auch wenn ich persönlich das völlig unsinnig finde: Sollte dies der Fall sein, hältst du dich natürlich bitte unbedingt daran! Wie immer gilt für jeden Tipp auf dieser Website, dass er nur so lange Bestand hat, wie du keine anderslautende Vorgabe deiner eigenen IHK bekommen hast.
Fazit
Schau dir vor Abgabe deiner Projektdokumentation noch einmal jedes Artefakt im Anhang an und überlege, ob es wirklich sinnvoll ist und dem Prüfer einen Mehrwert bietet. Kann der Leser anhand des Artefakts deine technische und fachliche Qualifikation bewerten? Oder füllt das Artefakt nur Seiten auf, die du anders besser hättest nutzen können?
Viele Projektdokumentationen müssen abgewertet werden, weil wichtige Artefakte fehlen. Und das liegt häufig daran, dass die vorhandenen Artefakte so ausufernd in der Projektdokumentation dargestellt werden, dass einfach kein Platz für andere wichtige Inhalte mehr bleibt. Daher rate ich dir, so viele unterschiedliche Inhalte wie möglich in der Projektdokumentation zu zeigen, und dafür gegebenenfalls einzelne Artefakte so zu kürzen, dass alle uninteressanten Bestandteile wegfallen und nur der Kern übrig bleibt.
Hast du für deine Projektdokumentation auch Inhalte gekürzt oder hattest du Mühe, die Seitenzahl zu erreichen?
Weitere Infos zur Projektdokumentation
Du suchst noch mehr Tipps rund um die Projektdokumentation? Dann schau doch mal in diese Artikel- und Podcast-Kategorie: Alle Artikel rund um die Projektdokumentation.
Kennst du schon meine Microsoft Word-/LibreOffice-Vorlage für die Projektdokumentation? Unter dieperfekteprojektdokumentation.de kannst du sie herunterladen.
Und wenn du dich für meinen Newsletter einträgst, kannst du dir jetzt sofort meine Checkliste für die Projektdokumentation herunterladen.
Neueste Kommentare