Projektdokumentation[FIAE] - Implementationsphase

[Minerva/8]

Hallo Leute,

ich bräuchte nochmal Hilfe bei der Projektdokumentation.

Momentan bin ich bei meinem vorletzten Punkt "Implementation" bei welchem eben der ganze "Implementierungsprozess bla bla" beschrieben werden soll.

Nun bin ich aber extrem unsicher wie man das genau schreiben soll. Im Prinzip habe ich ja durch meine Gliederung die einzelnen Punkte welche abgearbeitet werden können. (Klasse A Implementiert, Klasse B implementiert, Test Script A geschrieben, Test Script B geschrieben, Setup Script geschrieben usw....).

Dabei stellt sich mir eben die Frage: Schneide ich nur alle Themen an und erkläre wie ich das im groben gelöst habe oder gehe ich auch soweit das ich Elemente aus der verwendeten Sprache erkläre ? Bspw.

Funktion A wurde so realisiert ....Damit dies so funktioniert wurde auf die async/await (Javascript) Syntax zurückgegriffen, welche bewirkt das asynchrone Funktionen ...... oder

Um das Projekt umzusetzen wurde Framework XYZ eingesetzt welches sich bestens zur Erstellung von XYZ Applikationen eignet. Framework XYZ setzt dabei auf das MVC Pattern welches Vorteile XYZ mit sich bringt...

Ich hoffe Ihr versteht was ich meine. Eventuell könnt Ihr ja auch kurz beschreiben wie Ihr das gelöst habt^^

Vielen Dank!

 

[Gast default1990]

Ich bin sehr gespannt auf die Antworten, da ich gerade dasselbe Problem habe.

[neinal]

Ich weiß, dass es nicht einfach ist so eine Doku zu schreiben. Deshalb haben hier im Forum viele Leute ihre Dokus hochgeladen, nachdem die Prüfung vorbei war. Am besten lest ihr euch mal die ein oder andere durch. Das hilft oft schon.

Hier ist zum Beispiel meine: Doku

Ich bin nicht darauf eingegangen, welcher Befehl was auslöst. Ich wurde auch in der Prüfung nur eine technische Frage zur Umsetzung gefragt. Und das war, warum ich an Stelle X eine Kopfgesteuerte Schleife benutzt habe. Und keine Fußgesteuerte. 

Uns wurde gesagt, dass wir die Doku so schreiben sollen, dass sie jeder verstehen kann. Auch, wenn er nicht im Thema drin ist. Dementsprechend habe ich mich dazu entschieden die Doku nicht sehr technisch zu schreiben. Habe damals die Doku meinem Vater in die Hand gedrückt, zum lesen und ihn gebeten mir alles zu markieren, dass er nicht versteht. Das habe ich dann nochmal umgeschrieben

[Minerva/8]

Vielen Dank für die Antwort und deine Doku!

Ja im Internet findet man viele Dokus, aber diese unterscheiden sich Teils extrem. Wo Person A wirklich richtig ins Detail geht und auch seinen ganzen Code als Anhang mitliefert, schreibt Person B nur wirklich das nötigste und hängt da villt. nur ein zwei kleine Codeabschnitte dran. 

Vor allem wenn man das Projekt nicht so "professionell" machen konnte, wäre es wahrscheinlich eher ein Nachteil wenn man da alles offen legt...

 

[neinal]

Nix zu danken

Ja, es ist schwierig da zu differenzieren. Vor allem findet man im Internet eben auch Dokus ohne Angabe mit welchem Ergebnis diese bewertet wurden. Da ist es halt auch echt schwer einzuschätzen, ob die Doku dir weiter hilft, oder nicht.

Habt ihr vielleicht die Möglichkeit im Betrieb, oder in der Schule, jemandem die Doku zum lesen zu geben? Wir hatten damals in der Schule den ein oder anderen Lehrer der IHK Prüfer ist/war und sich bereit erklärt hat, die Dokus zu lesen und Feedback zu geben.

Dafür muss man aber natürlich relativ frühzeitig damit fertig sein.

[Minerva/8]

Leider keine der aufgezählten Möglichkeiten ? und die Leute wo die Doku lesen haben dann zu 99% keine Bewertungsmatrix der IHK im Kopf oder wissen überhaupt nicht auf was es ankommt^^.

Aber es gibt natürlich auch Sinn es so zu schreiben damit es auch "Normalos" verstehen. Für technische Sachen schreibt man ja schließlich auch noch Anwender/Entwicklerdokus, weswegen ich mich da jetzt auf das wesentlichste konzentriere.

Nochmals vielen Dank!

Bearbeitet 15. November 2018 von Minerva/8

[neinal]

Man muss halt immer bedenken, dass die IHK Prüfer "ganz normale Menschen" sind. Und es kann durchaus vorkommen, dass für sie das Thema neu ist. Mein Projekt habe ich im SAP Bereich gemacht. Ich weiß bis heute nicht, ob einer der Prüfer bisher jemals mit SAP gearbeitet hat. Deshalb lieber etwas weniger technisch ausführen. Damit der Prüfer am Ende weiß, was du gemacht hast  

Nix zu danken.

[arlegermi]

Ich habe damals im Implementierungskapitel vor allem die Architektur der Lösung besprochen - unterfüttert mit DFDs und Klassendiagrammen sowie ein paar Code-Auszügen.

[Gast default1990]

Ich glaube ich muss meine Danksagung zurücknehmen, verglichen mit deiner Doku sieht meine aus, als hätte ein betrunkener Vierjähriger sie mit Buntstiften auf eine Tapete gekritzelt.

Ist es wohl zu spät, noch auf Bäcker umzuschwenken?

[KeeperOfCoffee]

Hast du dir während der Realisierung keine Notizen gemacht? Wenn nicht würde ich dir empfehlen, einfach mal einen Text zu schreiben, was du alles in welcher Reihenfolge gemacht hast und warum. Was musstest du realisieren um weiter an Punkt Y zu arbeiten. Wie hast du die Implementierung geplant (du wirst ja nicht einfach "drauf los" programmiert haben, oder?). Du hast ja auch sicher beschrieben, nach welchem Modell zu arbeitest.

Diesen Plan würde ich durchgehen und die wichtigsten Punkte rauspicken. Hilfsfunktionen u.ä. sind nicht von Interesse. Zu den Interessanten Teilen kannst du dann noch im Anhang Code-Auszüge und Diagramme zur Verfügung stellen.

vor 10 Minuten schrieb jkcoding:

verglichen mit deiner Doku sieht meine aus

Ich denke die meisten Leute sind von der eigenen Doku weniger überzeugt.

Bearbeitet 15. November 2018 von KeeperOfCoffee

[neinal]

vor 17 Minuten schrieb jkcoding:

Ich glaube ich muss meine Danksagung zurücknehmen, verglichen mit deiner Doku sieht meine aus, als hätte ein betrunkener Vierjähriger sie mit Buntstiften auf eine Tapete gekritzelt.

Ganz ehrlich? Ich fand meine Doku von Tag zu Tag schlechter. Ich glaube es ist normal, dass man da nicht wirklich von sich überzeugt ist. Mit der Benotung hätte ich niemals gerechnet.

Ich kann mir nicht vorstellen, dass deine Doku so schlecht ist, dass du besser zum Bäcker umschulen solltest Das wird schon. 

Wirklich schlechte Dokus sieht man eher selten.

[Gast default1990]

vor 12 Minuten schrieb KeeperOfCoffee:

Zu den Interessanten Teilen kannst du dann noch im Anhang Code-Auszüge und Diagramme zur Verfügung stellen.

Uns wurde an mehrereren Stellen und immer wieder davon abgeraten, überhaupt Code in die Projektdoku zu nehmen, mit der Begründung, man würde nur unnötig Angriffsfläche bieten. 

[neinal]

vor 2 Minuten schrieb jkcoding:

Uns wurde an mehrereren Stellen und immer wieder davon abgeraten, überhaupt Code in die Projektdoku zu nehmen, mit der Begründung, man würde nur unnötig Angriffsfläche bieten. 

Man kann mit fast allem Angriffsfläche bieten. Deshalb nur Code rein packen, den man im Zweifel auch zu 100% erklären und jede Frage dazu beantworten kann

Ein paar Auszüge gehören für mein Empfinden aber schon auch in die Doku.

[KeeperOfCoffee]

 

Gerade eben schrieb jkcoding:

unnötig Angriffsfläche bieten. 

Tja ich schrieb im Antrag, dass ich Code nach Wunsch meines Unternehmens nicht veröffentlichen darf => Antrag abgelehnt.

Am Ende musste ich Pseudo-Code reinschreiben. Ich hatte alles Mögliche an Diagrammen, Bildern und PseudoCode drinnen. 

Begründung war, dass man ohne Code Auszüge sozusagen nicht die fachliche Eignung nachvollziehen kann oder so

[Gast default1990]

Es ist schon erstaunlich, dass einem jeder etwas anderes erzählt und trotzdem irgendwie fast jeder den Abschluss schafft.

[Minerva/8]

vor 10 Minuten schrieb KeeperOfCoffee:

 

Tja ich schrieb im Antrag, dass ich Code nach Wunsch meines Unternehmens nicht veröffentlichen darf => Antrag abgelehnt.

Am Ende musste ich Pseudo-Code reinschreiben. Ich hatte alles Mögliche an Diagrammen, Bildern und PseudoCode drinnen. 

Begründung war, dass man ohne Code Auszüge sozusagen nicht die fachliche Eignung nachvollziehen kann oder so

Gibt es dafür nicht noch das Fachgespräch (zum testen der fachlichen Eignung)? 

Wenn Code so wichtig ist kann man ja auch sein Git Repo als Link mit rein packen, da haben die genug zum sichten

Bearbeitet 15. November 2018 von Minerva/8

[KeeperOfCoffee]

vor 4 Minuten schrieb jkcoding:

Es ist schon erstaunlich, dass einem jeder etwas anderes erzählt

Das liegt daran, dass jeder wohl unterschiedliche "Prüfungspaten/patin" (diejenige/derjenige  deine Doku durchgehen und sich mit deinem Projekt auskennen) hat (bzw es halt viele gibt). Dieser lässt natürlich, ist ja ein Mensch, seinen subjektive Meinung und seine Erfahrung in die Bewertung mit einfließen. Dieser Prüfer kann einen super Tag gehabt haben oder einen schlechten. Er kann hoch motiviert sein, oder schon die Xte Doku heute gelesen haben.

Bearbeitet 15. November 2018 von KeeperOfCoffee

[neinal]

Das ist halt leider wirklich so. Jede IHK kocht ihr eigenes Süppchen. Und fordert etwas anderes.... 

Deshalb ist es wichtig als ersten Schritt, sich die Anforderungen der eigenen IHK zu Gemüte zu führen.

[stefan.macke]

 

vor 6 Stunden schrieb Minerva/8:

Funktion A wurde so realisiert ....Damit dies so funktioniert wurde auf die async/await (Javascript) Syntax zurückgegriffen, welche bewirkt das asynchrone Funktionen ...... oder

Von solchen Beschreibungen würde ich abraten! Das ist dicht dran an "In Zeile 1 wird die Variable i um 1 erhöht". Trivial und uninteressant! Beschreib lieber einen interessanten Algorithmus, den du entwickelt hast, oder das große Ganze (Architektur, Klassenstruktur, Workflow). Dass du eine Schleife programmieren kannst (oder in deinem Fall einen asynchronen Aufruf), davon gehen wir aus, sonst hättest du den falschen Beruf gewählt. Bei einem 70-stündigen Projekt findest du sicherlich etwas Spannenderes für die Doku als die zeilenweise Erläuterung einer einzelnen Funktion oder eines allgemeinen bekannten Sprachbestandteils.

vor 4 Stunden schrieb jkcoding:

Uns wurde an mehrereren Stellen und immer wieder davon abgeraten, überhaupt Code in die Projektdoku zu nehmen, mit der Begründung, man würde nur unnötig Angriffsfläche bieten. 

Da würde ich klar widersprechen. Der Code ist ein wichtiges Arbeitsergebnis deines Projekts (sofern du denn etwas programmiert hast). Und der gehört auch (!) in die Doku. Zusätzlich zu anderen Artefakten wie UML-Diagrammen, ERM usw. Natürlich macht man sich damit "angreifbar", wenn damit gemeint ist, dass man dazu Rede und Antwort im Fachgespräch stehen muss. Allgemein gilt: Was man nicht versteht und/oder erklären kann, schreibt man besser nicht in die Projektdokumentation oder -präsentation.