pdoku_fiae Projektdokumentation - Aber wie?

[Radinator]

Servus!

Vielleich kann mir ja wer von Euch helfen. Und zwar:

Ich hab als Abschluss-Projekt den Auftrag bekommen, ein Lager von der Vogelperspektive aus auf einem im Lager hängendem Bildschirm anzeigt und mit Farben zu kennzeichnen, wie belegt das Lager ist.

Wo ich jetzt allerding absolut keinen Plan habe ist, wie ich das ganze jetzt in der Dokumentation verwursteln soll.

Im Prinzip dient ja - jedenfalls meiner Meinung, darf aber auch korrigiert werden - die Dokumenation der Erklärung WIE genau ein Programm zu verwenden ist, bzw WAS es macht. Dabei ist natürlich der WIE-Anteil wesentlich größer, als der WAS-Anteil (gefühlt 95:5).

Daher: Was gehört - Eurer Meinung nach - in so eine eine Dokumentation, die ein Programm beschreibt, welches als eizigen Zweck die Anzeige von Etwas hat und es sonst zwischen dem Prgramm und dem "User" keine weiter Interaktion gibt.

Mein Ansatz wäre gewesen, dass ich den kompletten Quellcode (~700 Zeilen LOC) ausführlich kommentiert da reinschreibe. Aber das ist wohl nicht "The Yellow of the Egg".

 

Danke schon mal für die Antworten

Lg Radinator

[Asura]

Letztendlich hast du eine Gliederung. Wie die Aussieht ist mir egal, folgend einfach nur ein Beispiel aus dem Stegreif

1.    Einleitung
1.1  Einleitung (Das Projekt ist entstanden durch....)
1.2  Zu meiner Person (Ich bin .... und arbeite bei ...... )
1.3 Der Ausbildungbetrieb (Mein AG ist tätig im Bereich ....)
1.4 Abweichungen zum Projektantrag (falls vorhanden)
2.      Ausgangssituation
2.1        Ist-Zustand (Aktuell ist das so .... umgesetzt)
2.2        Projektziel (Ziel ist..)
2.3        Projektumfeld (Das Umgeld ist Firma .... und .....)
2.4        Restriktionen (Klare Abgrenzung deiner Aufgaben)
2.5        Schnittstellen (.... spricht für sich)
3.      Projektplanung
4.      Ressourcen und Ablaufplanung
5.      Projektrealisierung
6.      Inbetriebnahme
7.      Projektergebnisse
7.1        Soll-Ist Vergleich
7.2        Kosten-Nutzen Analyse
7.3        Fazit
8.      Anhang
8.1        Quellcodeauszug
8.2        Abbildungsverzeichnis
8.3        Glossar
8.4        Abkürzungsverzeichnis
8.5        Quellenverzeichnis

Da ich dir keine keine komplette Gliederung vor die Nase legen will, mach ich keine weitere Unterschritte.. Natürlich will jede IHK etwas andere in Dokumentation sehen, allerdings sind meiner Meinung nach die oben genannten Punkte als Beispiel gut gewählt.

Diese Gliederung arbeitest du von oben nach unten durch.

[.Phil]

Die IHK will in der Doku keine Anwenderdokumentation oder Programm-/ Modulbeschreibung haben, sondern du sollst dort detailliert und mit Begründung die einzelnen Schritte bei der gesamten Umsetzungphase deines Projekts darlegen. Dazu gehört von der Planung über die Umsetzung bis zu den Tests und zum Rollout alles. 

Schau mal hier, da sind ein paar sehr gute Beispieldokus aufgeführt

[Radinator]

Vielen Danke Euch beiden!

@.Phil: Genau darum ging es mir auch: Wollen die eine Dokumentation zu Benutzung oder eine Dokumentation wie ich das Programm erstellt habe.  *daumen hoch*

@Asura: Danke auch für deinen Beitrag, sehr hilfreich! *daumen hoch*

Lg Radinator

[MagProgrammierenNichtMal]

@Asura Ich finde diese Gliederung schon super aber was soll man denn bei "Zu meiner Person schreiben"? Meintest du so was in der Art?

Zitat

Ich bin Foo und arbeite bei der Bar Systemhaus GmbH in der Abteilung “Forschung und Entwicklung”. In dieser Abteilung entwickle ich firmeninterne Tools oder verwirkliche in Kooperation mit meinen Teammitgliedern Großprojekte für Kunden. Ich entwickle hauptsächlich Webanwendungen mithilfe  von Django, Flask, NodeJS oder Meteor und benutze als Datenbank, je nach Verwendungszweck, MySQL, MariaDB, MongoDB, PostgreSQL oder Redis.

 

Bearbeitet 2. April 2016 von MagProgrammierenNichtMal

[stefan.macke]

Bitte nicht! Das interessiert niemanden und ist auch noch in der Ich-Form geschrieben. Das geht gar nicht.

Im Zweifel komplett weglassen und stattdessen sinnvolle - technische - Inhalte einbauen, die auch bewertet werden können.

[MagProgrammierenNichtMal]

@stefan.macke Ist der Rest der Gliederung legitim?

[Asura]

Am 2.4.2016 um 20:41 schrieb stefan.macke:

Bitte nicht! Das interessiert niemanden und ist auch noch in der Ich-Form geschrieben.

Scheint wieder so n IHK-Ding zu sein.. Sehr viele hatten eine Beschreibung ähnlich wie:

1.2  Zu meiner Person (Ich bin .... und arbeite bei ...... )
1.3 Der Ausbildungbetrieb (Mein AG ist tätig im Bereich ....)

Meinen Punkten zufolge hatte es anscheinend auch nicht geschadet. Aber ich verstehe, dass es auch nicht gerade sehr interessant ist..

 

[stefan.macke]

Ok, das ist gut zu wissen. Im Zweifel würde ich den Prüfern allerdings nicht meine Lebensgeschichte erzählen (oder noch schlimmer die des Unternehmens), sondern den wertvollen Platz für bewertbare (!) Inhalte nutzen.

Die Ich-Form geht allerdings meiner Meinung nach absolut nicht. Wir schreiben ja keinen Aufsatz, sondern eine technische Dokumentation. Und die muss sachlich formuliert werden.

[Asura]

In meinem Fall hatte ich kurz meinen AG erklärt. Also über ein paar Zeilen, wofür wir bekannt sind und wie groß wir sind. Technisch natürlich ziemlich uninteressant, aber uns wurde gesagt, dass eine kurze(!) Gesamtvorstellung relativ gern gesehen wird.

Zu meiner Person eben dann der eingesetzte Bereich, in welchem ich meine Ausbildung verbracht hab und meine Tätigkeitsbereiche dort. Also wenn ich nur Windows-Server administriert habe und ich aufeinmal im Linux-Bereich ein Projekt mache welches sehr gut und ohne Probleme verläuft wird man wahrscheinlich ein wenig skeptisch.

Ich stimme dir zu, den Part sollte man relativ gering halten. Bei der IHK-Nürnberg hatten wir letztendlich 20 Seiten "Platz" weshalb man sich wegen einer Zeile mehr oder weniger nicht Gedanken machen sollte. Man hat ja ziemlich viel Spielraum mit der Schriftgröße und Art gehabt.

Aber du hast Recht, im Zweifelsfall weglassen. Und Ja, die Ich-Form erinnert mehr an eine Geschichte als an eine technische Doku.

[DTJN]

Am 7.4.2016 um 08:25 schrieb stefan.macke:

Die Ich-Form geht allerdings meiner Meinung nach absolut nicht. Wir schreiben ja keinen Aufsatz, sondern eine technische Dokumentation. Und die muss sachlich formuliert werden.

Das scheint auch eher Auslegungssache als Gesetz zu sein. Ich war auch dieser Meinung und hatte in meinem Antrag zunächst Vollkommen darauf verzichtet. Mir wurde jedoch später von einem Mitglied des Prüfungsausschusses (IHK-Hamburg), in beratender Funktion, empfohlen, die Ich Form in meinem Projektantrag zu Nutzen, um die Eigenleistung klar herauszustellen.

Ein Beispiel:  " Zur Durchführung meines Projektes gehören die Erstellung eines Lastenheftes für die externen Dienstleister, die Angebotseinholung und die wirtschaftliche Betrachtung im Sinne einer Kosten-Nutzen-Analyse, die mich schlussendlich zu einer Kaufentscheidung führen soll." 

Der Antrag wurde ohne jegliche Beanstandung von dem tatsächlich für mich zuständigen Prüfer genehmigt.

[Asura]

Zitat

Der Antrag wurde ohne jegliche Beanstandung von dem tatsächlich für mich zuständigen Prüfer genehmigt.

Wer in diesem Forum mit liest, sieht, dass viele Anträge genehmigt werden die unserer Meinung nach gar nicht angenommen werden sollten. Der Großteil der hier antwortenden Personen sind keine Prüfer und können nur auf die Erfahrung zugrückgreifen um zu Antworten.

Es handelt sich nach wie vor um eine technische und sachliche Dokumentation, hier haben "Ich-Geschichten" nichts zu suchen. Die Geschmäcker jeder Prüfer sind verschieden. Ich habe oft den Satz von meinen Berufschullehrern (diverse Prüfer) gehört, dass sie nicht verstehen wie andere Prüfer bewerten und es immer eine endlose Diskussion über Dinge gibt, die man nicht diskutieren muss. (IHK-Nürnberg).

Schlichtweg sollte man soetwas nicht in der Ich-Form schreiben. Bevor ich in der "Ich-Form" schreibe, schreib ich lieber einen Satz am Anfang der Dokumentation:
"Wenn nicht explizit auf einen anderen Bearbeiter hingewiesen, werden alle beschriebenen Aufgaben vom Prüfling bearbeitet und gelöst". ... oder ähnliches.
Die "Geschichten-Form" lässt das ganze meiner Meinung nach nur unsachlich und "untechnisch" klingen.

Zitat

Ein Beispiel:  " Zur Durchführung meines Projektes gehören die Erstellung eines Lastenheftes für die externen Dienstleister, die Angebotseinholung und die wirtschaftliche Betrachtung im Sinne einer Kosten-Nutzen-Analyse, die mich schlussendlich zu einer Kaufentscheidung führen soll." 

 

Während der Durchführung des Projektes wird ein Lastenheft für den externen Dienstleister erstellt, des Weiteren werden Angebote für xxx eingeholt. Die wirtschaftliche Betrachtung durch eine Kosten-Nutzen-Analyse wird zu einer Kaufentscheidung führen.

Das wäre mein Beispiel.