Musterbeispiel Projektdokumentation?

[Mr Unix]

Moin Gemeinde!

Ich mache mir so langsam Gedanken ueber meine Projektdokumentation. Vielleicht wurden die Fragen ja schonmal gestellt, aber ich denke sowas waere ein Sticky wert:

- Wie sieht eine vorbildliche Projektdokumentation aus?

- Was sollte wie in der Projektdokumentation vermerkt sein?

- Wie umfangreich darf/soll/muss die Dokumentation sein.

- Soll nun das Projekt oder nur die Vorgehensweise im Projekt dokumentiert sein?

- Ist eine gewisse Einfuehrung in nicht selbstverstaendliche Themen/Technologien erwuenscht/unerwuenscht?

Einer meiner Lehrer meinte, dass das etwa 15 Seiten werden sollten, aber bei meinem Thema (Kernel Extensions fuer Mac OS X) komme ich mit Screenshots bestimmt ueber 50 Seiten.

Gibt es vielleicht von der IHK irgendwo ein Beispiel, eine Zusammenfassung oder eine Infoseite?

Ich weiss nicht ob sich hier irgendwelche Pruefer tummeln, aber auch von den Ausgelernten AEs waere ich ueber jede Art von Statement sehr dankbar, da das momentan doch noch sehr dichter Nebel ist.

[HappyHero]

Hier gilt wie immer: Jede IHK hat da so ihre eigenen Vorstellungen. Anrufen und Nachfragen ist die einzig sichere Lösung.

Ein Paar grundsätzliche Sachen kann ich dir aber ans Herz legen:

Wenn es in deiner Firma ein CI für Dokumente gibt, benutz es. Ansonsten verzichte lieber auf schnörkelleien. Seitenzahl, Datum, Name, Thema angemessen auf Kopf- Fusszeile verteilen, normalen Seitenrand lassen, im Textlayout konsistent bleiben (Absätze, Überschriften, Kapitelüberschriften, Bildunterschriften, Tabellen, etc. immer gleich Formatieren).

Aktuelle Textverarbeitungen leisten da mit Formatvorlagen gute Vorarbeit.

Ich bin mit einigen Screenshots, Diagrammen, Tabellen, etc. auf etwa 35 Seiten gekommen, allerdings die Vollständige Mappe mit Lastenheft, Plichtenheft, Dokumentation der Umsetzung, Technische Dokumentation.

Ob du das alles auch haben musst hängt natürlich von deinem Projekt ab.

Wenn du wirklich auf soo viele Seiten kommst, dann solltest du dir mal Gedanken darüber machen, wie viele von den Screenshots du wirklich brauchst.

Dokumentation bedeutet nicht, jeden Schritt den du ausführst, zu Knipsen und schön in einer Gallerie abheften, sonden es geht darum, dass du deine Entscheidungen begründest.

[Mr Unix]

Anrufen und Nachfragen ist die einzig sichere Lösung.

Die einfachste Loesung ist mir wiedermal nicht eingefallen! :upps

Seitenzahl, Datum, Name, Thema angemessen auf Kopf- Fusszeile verteilen, normalen Seitenrand lassen, im Textlayout konsistent bleiben (Absätze, Überschriften, Kapitelüberschriften, Bildunterschriften, Tabellen, etc. immer gleich Formatieren).

Ich wohlte das sowieso mit LaTeX machen. (Was anderes hab ich hier auch gar nicht...)

Ich bin mit einigen Screenshots, Diagrammen, Tabellen, etc. auf etwa 35 Seiten gekommen, allerdings die Vollständige Mappe mit Lastenheft, Plichtenheft, Dokumentation der Umsetzung, Technische Dokumentation.

Das ist ein weiterer Aspekt der mir zu schaffen macht. Das Projekt ist fuer ein Subunternehmen entstanden - Kein Pflichten- und Lastenheft. Sollte das Probleme geben?

Und du hast der IHK die technische Dokumentation gegeben? Ich wuerde mich bei dem Gedanken nicht wohl fuehlen, auch wenn die Pruefer und Kammer da Schweigepflicht haben... Ist das normal so? :confused: Mein Projekt ist nur eine Untermenge eines viel groesseren Projekts, dass ich umsetze und die technische Dokumentation ist bestimmt noch nicht bis zum Januar fertig...

Wenn du wirklich auf soo viele Seiten kommst, dann solltest du dir mal Gedanken darüber machen, wie viele von den Screenshots du wirklich brauchst.

Ich habe vier Bilder reingemacht, damit da ueberhaupt mal irgendwas grafisch dargestellt ist. Klassendiagramm, ein Ablaufplan, eine schematische Darstellung der Interaktion zwischen GUI und den Komponenten des Kernel sowie ein Bild der Anwendung selbst. Auch wenn ich die zwei Seiten rausnehme ist das immernoch mehr als mein Lehrer meinte....

Dokumentation bedeutet nicht, jeden Schritt den du ausführst, zu Knipsen und schön in einer Gallerie abheften, sonden es geht darum, dass du deine Entscheidungen begründest.

Nur mal rein zum Verstaendnis: Welche Entscheidungen? Ich greife auf Funktionen des Kernels zu. Viel Entscheidungsfreiheit bleibt mir da nicht. Das Einzige was ich erklaeren kann ist die GUI so wie ihre Schnittstelle zum Kernel und das was im Kernel wie ablaeuft. Ne Seite mit nem Fazit haengt noch am Ende, aber das war's.

Aber erstmal vielen Dank fuer deine Antworten! Ich werde bald die IHK anrufen (und wie es im Februar auch ausgeht wird es hier ein Feedback geben).

[HappyHero]

Ich hatte glaube ich 2 oder 3 Ansichten der fertigen Anwendung und je ein Codebeispiel einer Quellcode-Datei (nur einen Auszug) und eine Konfigurationsdatei (n bissn xml). Dazu ein Klassendiagramm und ein Use-Case-Diagram, außerdem etwas Beschreibung, was in welcher Reihenfolge angelegt wurde.

Das war die technische Dokumentation. Auf die Programmiersprache, genaue Abläufe, etc. bin ich nicht weiter eingegangen. Do solltest noch erwähnen, was für bereits fertige (externe) Komponenten (Frameworks, Bibliotheken, Rahmenbedingungen) du verwendet hast.

Dass die Prüfer mit deinen Daten vertraulich umgehen ist eine Selbstverständlichkeit.

Für mein Projekt wäre normalerweise auch nie ein Pflichtenheft gemacht worden, deshalb habe ich dann im Rahmen der Projekt-Doku eins erstellt.

Du sollst in deiner Dokumentation hauptsächlich deine Entscheidungen für die gewählte Umsetzung des Projektes begründen. Warum hast du das Projekt auf diese Weise umgesetzt, welche Alternativen hätte es gegeben, warum wurden die ausgeschlossen.

Wichtig ist auch der kaufmännische Aspekt. Was hat das Projekt gekostet, hat sich das gelohnt, wäre evtl. eine gekaufte Software und deren Einführung billiger gewesen?

[Mr Unix]

Ich hatte glaube ich 2 oder 3 Ansichten der fertigen Anwendung und je ein Codebeispiel einer Quellcode-Datei (nur einen Auszug) und eine Konfigurationsdatei (n bissn xml). Dazu ein Klassendiagramm und ein Use-Case-Diagram, außerdem etwas Beschreibung, was in welcher Reihenfolge angelegt wurde.

Das war die technische Dokumentation. Auf die Programmiersprache, genaue Abläufe, etc. bin ich nicht weiter eingegangen. Do solltest noch erwähnen, was für bereits fertige (externe) Komponenten (Frameworks, Bibliotheken, Rahmenbedingungen) du verwendet hast.

Mhja... Da sind IMO einige gute Anhaltspunkte dabei. Danke.

Für mein Projekt wäre normalerweise auch nie ein Pflichtenheft gemacht worden, deshalb habe ich dann im Rahmen der Projekt-Doku eins erstellt.

Nun mein Projekt wird teil eines "hauseigenen" Produktes. Ich bin mir da was Pflichtenheft angeht absolut nicht sicher. :confused:

Du sollst in deiner Dokumentation hauptsächlich deine Entscheidungen für die gewählte Umsetzung des Projektes begründen. Warum hast du das Projekt auf diese Weise umgesetzt, welche Alternativen hätte es gegeben, warum wurden die ausgeschlossen.

Da lag ich dann ja wohl auch nicht so weit entfernt von. Dann werde ich wohl Einiges vom technischen Teil einfach rausnehmen.

Wichtig ist auch der kaufmännische Aspekt. Was hat das Projekt gekostet, hat sich das gelohnt, wäre evtl. eine gekaufte Software und deren Einführung billiger gewesen?

Ich vermute stark, dass es dort keinen kaufmaennischen Aspekt gibt. Klar, es gibt einen internen Stundensatz (Arbeitskraft/Stunde = \d+ Euro), aber der wird verwendet um zu ueberpruefen ob ein Einsatz rentabel war. In meinem Fall ist das Produkt ja noch nicht mal fertig und Alternativen (egal ob Alternativprodukte oder Komponente der Entwicklung) gibt es (zumindest noch) keine. Ob ich da einfach etwas erfinden sollte?

Auf jeden Fall vielen Dank fuer deine Tipps! Ich werde mal mit meinem Lehrer reden und ggf. bei der IHK nachhaken.

[HappyHero]

Ich vermute stark, dass es dort keinen kaufmaennischen Aspekt gibt. Klar, es gibt einen internen Stundensatz (Arbeitskraft/Stunde = \d+ Euro), aber der wird verwendet um zu ueberpruefen ob ein Einsatz rentabel war. In meinem Fall ist das Produkt ja noch nicht mal fertig und Alternativen (egal ob Alternativprodukte oder Komponente der Entwicklung) gibt es (zumindest noch) keine. Ob ich da einfach etwas erfinden sollte?

Naja, dann kannst du ja z.B. schreiben, dass es keine Software/Komponente gibt, die euren Anforderungen genügt.

Dabei hast du auch gleich die Möglichkeit, die Anforderungen einmal zu definieren (und schon hast du ein Lastenheft) und dann deren Umsetzung festzulegen (und schon hast du ein Pflichtenheft) und die dann begründen (und schon hast du deine Dokumentation). ^^