Dokumentation: Details und Seitenanzahl

[Horus3]

Hallo.

Dies ist eine Frage, die mir sicher meine zuständige IHK beantworten könnte, doch der für mich zuständige Ansprechpartner ist noch für eine Woche im Urlaub und eine alternative Person gibt es laut Aussage seines Kollegen dort nicht, der mir Fragen zur Projektdoku beantworten kann.

Zur Zeit bin ich an meiner Projektdoku. Laut den Vorgaben der IHK soll die Doku ja höchstens 10 Seiten lang werden, Deckblatt, Inhalt und Anlagen ausgenommen.

Ich möchte nämlich auch jetzt gerade nicht für eine Woche das Projekt unterbrechen und auf meinen IHK-Ansprechpartner warten. Zum einen bin jetzt gerade gut dabei und "es fließt" und zum anderen möchte ich natürlich die Doku wie ursprünglich geplant bis nächste Woche fertig haben, um danach nochmal Endspurt für die Prüfungsvorbereitungen machen zu können.

Thematisch geht es um einen Web- und Datenbankserver. Das Projekt beinhaltet auch zum Großteil PHP- und SQL-Code.

Nun stelle ich fest, dass ich nach meiner Vorstellung, wie detailreich die Quellcodes beschrieben werden sollen, mit 10 Seiten nicht hinkäme. 8 Seiten sind es bis jetzt und wenn ich in dieser Form weiter dokumentiere, würden es sicher 14-16 Seiten werden.

Nun habe ich zwischendurch immer mal wieder Passagen geändert und versucht so komprimiert zu beschreiben und dabei auch immer wieder Text einsparen können, doch auch so käme ich wie gesagt auf mehr als 10 Seiten.

Da ich externer Prüfling bin und keine alternativen Ansprechpartner habe, kann mir vielleicht hier jemand aus Erfahrung mitteilen, ob als FISI speziell die Quellodes der PHP-Skripte und SQL-Abfragen genaustens erklärt werden müssen oder ob beispielsweise Struktogramme genügen und der Quellcode dann mit Bemerkungen innerhalb ausreichend ist.

Das Beschreiben der Quellcodes nimmt nämlich schon viel Platz in Anspruch (obwohl die Quelltexte und andere wichtige Aufstellungen/Tabellen bereits in den Anhang verschoben wurden).

Noch 'ne Frage zu den Anhängen in der Doku. Sollte es dort auch ein Limit geben oder ist das theoretisch egal, wieviel Seiten der Anhang benötigt?

[gimbo]

Nun stelle ich fest, dass ich nach meiner Vorstellung, wie detailreich die Quellcodes beschrieben werden sollen, mit 10 Seiten nicht hinkäme. 8 Seiten sind es bis jetzt und wenn ich in dieser Form weiter dokumentiere, würden es sicher 14-16 Seiten werden.

Also wenn deine Dokumentation aus der Beschreibung und Kommentierung von Quellcode besteht, dann würde ich mir schleunigst Gedanken machen.

[Crash2001]

Also ich weiss nicht, was genau du in der Doku da beschreiben willst. Eigentlich gehört dort rein, was genau du machen willst (Projektbeschreibung), dann die Möglichkeiten, wie das ganze realisiert werden kann, gefolgt von der Auswahl einer Möglichkeit davon, sowie eine wirtschaftliche Betrachtung des ganzen und dann halt wie das Projekt verlaufen ist und wie die Anwendung dann letztendlich funktioniert. Eventuell noch ein Datenbankdiagramm mit den Tabellen, falls eine Datenbank benutzt wird.

Jeden einzelnen Programmteil oder jede Funktion oder jedes Objekt musst du da definitiv nicht en detail beschreiben. Das sollte im Quelltext direkt mit aussagekräftigen Namen und entsprechenden Kommentaren gemacht werden, was welcher Teil macht.

Hast du dir mal ältere Projekt-Dokus von FISI-Projekten angeschaut? Falls nicht, hier im Forum sind soweit ich weiss ein paar Dokus verfügbar.

Bearbeitet 14. Oktober 2010 von Crash2001

[Grand0815]

Nur mal zum Verständniss, bist du FiSi oder FiAE ?

Denn als FiSi erscheint mir PHP und MySQL nicht so passend?!

[Horus3]

Also wenn deine Dokumentation aus der Beschreibung und Kommentierung von Quellcode besteht, dann würde ich mir schleunigst Gedanken machen.

Eben aus diesem Grund habe ich hier ja die Frage gestellt.

Das soll jetzt keine Unhöflichkeit sein, aber bitte keine Belehrungen oder einfach nur Anmerkungen zu meiner Frage bringen, das hilft mit nämlich nicht weiter.

[Horus3]

Nur mal zum Verständniss, bist du FiSi oder FiAE ?

Denn als FiSi erscheint mir PHP und MySQL nicht so passend?!

FISI. Das Projekt wurde ohne "wenn" und "aber" von der IHK genehmigt.

[Crash2001]

Nur mal zum Verständniss, bist du FiSi oder FiAE ?

Denn als FiSi erscheint mir PHP und MySQL nicht so passend?!

DAs kommt ganz drauf an, welchen Stellenwert die reine Programmierung dabei einnimmt.

[Taramur]

Also bei uns heißt es laut IHK 10-15 Seiten, das würde dann ja passen. Als ich die Genehmigung meines Projektes erhalten habe, habe ich auch ein Informationsblatt über die Projektdokumentation bekommen in der all diese Fragen geklärt werden.

Die Anhänge sind bei mit soweit ich weiß nicht auf eine bestimmte Anzahl beschränkt. Aber ist ja jedem klar das man es nicht übertreiben sollte und 50 Seiten Anhang einbaut

Grüße

Taramur

[Crash2001]

Der Anhang kann ja auhc nciht auf eine bestimmte Anzahl von Seiten beschränkt werden, wenn der Quellcode mit drangehängt werden soll... alleine der könnte ja je nachdem schon recht umfangreich sein...

[Pikachu]

Moin...

Bei uns hier in Rostock heißt es ebenfalls 10-12 Seiten für die Doku, aber da ich das gleiche Problem mit der länge habe, habe ich bei der IHK angerufen und die sagten mit das das nur ein Richtwert ist und man ohne bedenken auch Dokus mit 13,14 oder 15 Seitewn abgeben kann, man sollte es natürlich nicht übertreiben...

Pika pi...

[Horus3]

Heute habe ich endlich Info von meiner zuständigen IHK bekommen können.

Da hieß es also auch, dass es auch 12 oder 13 Seiten sein dürfen.

Wichtig soll dabei eben nur sein, dass in dem Hauptteil nur das Wesentliche drin steht. Anhänge mit Tabellen, Quellcodes, Screenshots etc. könne ich soviel anhängen wie ich wolle bzw. soviel wie eben notwendig seien.

[gizmo711]

Grundsätzlich musst du in deiner Doku nicht deinen Quellcode beschreiben. Es interessiert - wenn überhaupt - vielleicht die grobe Funktionsweise der Anwendung, nicht aber, wie welcher Verarbeitungsschritt funktioniert, und warum du eine IF-Bedingung und keinen CASE verwendet hast etc. pp..... In der Doku kommt es gar nicht so sehr auf das Produkt als viel mehr auf den Verlauf deines Projekts an.

Ich bin in der Doku gar nicht auf den Quellcode eingegangen, außer insofern, dass ich im Punkt "Projektdurchführung" in den einzelnen Phasen beschrieben habe, welche Teile der Anwendung wann entstanden sind....

In den Anhang habe ich auch nicht den kompletten Quellcode angehängt, sondern lediglich die Datendeklarationen und die Ablauflogik meiner Anwendung. Wie die einzelnen Module aufgebaut waren, wie welcher SELECT gestaltet wurde oder wie die Daten im Detail aufbereitet oder verarbeitet wurden, hab ich gar nicht mit angegeben. Ich hatte so bereits 10 Seiten Quellcode, dazu Screens, Anwenderinformationen, Struktogramme, Anforderungsprotokoll etc... der ganze Quellcode mit knapp 45 Seiten hätte da die Doku gesprengt!

Ich würde mich also an dieser Stelle lieber etwas zurückhalten, es sei denn es ist von der IHK gewünscht, dass du den kompletten Quellcode mit anhängst....