Dokumentation für Programm erstellen

[Kaiborg]

Hi!

Ich habe für die Schule ein Projekt geschrieben, was noch nich 100%ig funktioniert :wall: , mein Infolehrer :warn: war damit nich ganz einverstanden, und hat gesagt, er möchte dazu dann bitte eine Dokumentation haben :evil: , nur leider hat er nich gesagt, wie man eine Dokumentation zu schreiben hat :wiejetzt: , und auch nach intensiver Internetsuche habe ich keine vernünftige Anleitung dazu gefunden.
Wär schön, wenn mir jemand weiterhelfen könnte.
Danke im Voraus :P

[CalganX]

Hi,
du hast eigentlich da Freiheit. Zumindest was das Format angeht. Meistens schreibe ich Dokumentationen in PDF (LaTeX bei mathematischen Sachen oder OpenOffice.org bei anderen Dingen). Allerdings kannst du das ganze auch in Form einer OnlineHilfe schreiben (.chm) oder ein einfaches Worddokument schreiben.
Zu Allen Möglichkeiten findest du in der DP was entsprechendes.

Der Aufbau sollte - meiner Meinung nach - ungefähr so aussehen:

1. Einführung - Was macht dein Progamm? Womit hast du es geschrieben? Was ist der Sinn? etc.
2. Dateien - Welche Dateien liegen dem Programm bei? Welche Funktion hat welche Datei? etc.
3. Algorithmen - Welches Problem soll das Programm lösen? Welchen Algorithmus hast du verwendet? etc.
4. Source-Dokumentation - Welche Funktion macht was? Erkläre den SourceCode! etc. (nur bei OpenSource)
5. Abschluss - Quellen der Algorithmen, Dank ( ;) ), etc.

Das im Groben. So sieht's bei mir zumindest meistens aus.

Chris

[HAF4ever]

oder einfach nur ein paar (* kommentare *) einfügen ...
wo halt drinnen steht was das prog macht bzw. machen soll

[Kaiborg]

Ok, danke!

Dann werde ich das mal noch bis morgen machen, sieht ja nicht so schwer aus :) , aber eine Frage noch, muss der Quellcode rein??

[HAF4ever]

der ganze source zahlt sich nicht aus ...
aber den code der wichtigsten prozeduren und funktionen schadet sicher nicht ...

[Luckie]

Zu den Algorithmen sollte man noch die mathematischen Grundlagen etwas erörtern. Und zum Schluss gehören da noch ein paar Testeingaben mit den Ausgaben dabei, sowohl Extremwerte, als auch normale. Und dabei müssen auch die Grenzen aufgeziegt werden, also bei welchen Werten dein Programm versagt.

[Karsten]

Die Funktionen sollten anhand von Flow-Charts beschrieben werden (nur die wichtigen, um prinzipielle Funktionsweisen zu erklären) und auf keinen Fall Quellcode in die Dokumentation reinnehmen.

Und wie Luckie schon sagte, 'mathematische Grundlagen' sind immer wieder sehr geeignet und auch wichtig.

Sollte sich irgenwann mal diese Frage während einer Diplomarbeit oder ähnliches stellen, kann ich da nur auf Erfahrungswerte zurückgreifen:

Note 1-2 bei denen die auf Quellcode verzichten und sich um prinzipielle Dinge gedanken machen

Note 3-4 bei denen die den Quellcode ans Ende kopieren um die Anzahl der Seiten zu erhöhen.

Gruß,
Karsten

[fenni]

Wichtig ist auch eine Erklärung, dass du das Programm ohne fremde Hilfe erstellt und eventuelle externe Quellen angegeben hast.

Der Quellcode gehört wenn überhaupt nur in den Anhang, ich würde ihn aber ganz weglassen und nur die wichtigsten Funktionen/Prozeduren in einem extra Kapitel über den Programmablauf an sich erläutern.

MfG
fenni

[HAF4ever]

wenn man schon keinen quellcode reinschreiben soll ...
wie siehts mit ablaufdiagrammen aus...? macht das einen guten eindruck wenn man für die wichtigsten algorythmen solche diagramme dazuzeichnet?

[Hansa]

Je nachdem, was Du genau jetzt meinst, vielleicht ja etwas anderes als ich, aber sehe ich irgendwo so ein paar bunte Bauklötze, Pfeile, die ins Nirwana zeigen und so nen Kram, dann hat dieses Programm bei mir schon verloren. Wie gesagt, nur meine Meinung :!: Steht Dein Pauker auf so nem Kram, dann mach es halt.

[Luckie]

Warum sollten die ins Nirvana zeigen?

[Kaiborg]

hey, das is ja mehr als ich erwartet habe :-D , danke jungs (und evtl. mädels), ich glaube ich werde eure Hilfe öfter mal in Anspruch nehmen

cu Kaiborg

[Rainer_Unger]

Hallo Karsten,

ich war lange Zeit in der Uni tätig und hab selbst Diplomarbeiten abgenommen.
Ob der Sourcecode in der Doku drin ist oder nicht spielt überhaupt keine Rolle.
Wir beurteilten die Arbeiten nach dem Inhalt. Wir bestanden auf dem vollständigen Sourcecode. Ich kann ohne weiteres am Sourcecode sehen ob der Code von der Person stammt, die ihn abgegeben hat oder nicht.

Dann noch etwas: deine Notenskala ist etwas merkwürdig.
Heute gibts die Noten von 1 bis 2. Schlechtere Noten gibts nur gnadenhalber um demjenigen keine 5 machen zu müssen. 2 entsprach bei uns schon einer 4 in der Schule.

Ganz wesentlich geht jedoch der Diplomvortrag in die Note ein. Wenn du einen mittelmässigen Vortrag abgeliefert hast und vorher ein misserabler
Zeitgenosse dran war, macht das Uu eine halbe Note aus.

Dies hier ein paar Bemerkungen zur Diplomarbeit und Dokumentation.

Rainer Unger

[Karsten]

Hallo Rainer,

das waren halt Erfahrungswerte; interessant daß eine 3 im Grunde einer 5 entspricht. Und die Zusammensetzung der Gesamtnote ist mir auch schon bekannt, es sei denn es hat sich in den letzten Jahren einiges daran geändert.

Ich möchte hier erst einmal anmerken das in meinem Fachgebiet nicht unbedingt die Programmierung im Vordergrung stand. Die Programme waren in erster Linie Simmulationen oder dienten der Auswertung und Aufarbeitung von Messdaten. D.h., die Software war nur mittel zum Zweck. Ich selber mußte mir die C-Programmierung erst einmal während der Diplomarbeit beibringen.

Es gab halt zwei sorten von Studenten:

1. Den Lötkolben schon mal einschalten bevor ich überhaupt weiß was ich machen will bzw. die erste Zeile Programmcode geschrieben bevor ich überhaupt weiß wofür das Programm gut sein soll.

2. Erst grübeln, dann dübeln

Bei (1) wurden die wenigen Seiten die geschrieben wurden am Ende mit dem Ausdruck des Quellcodes aufgefüllt. War das Verhältnis zwischen Ausarbeitung/Auswertung und Quellcode nicht gerade rosig, hat sich das natürlich auch in der Note wiedergespiegelt.

Bei (2) wurde erst einmal festgelegt was man erreichen bzw. untersuchen wollte, dann welche Mittel und Wege man dafür benutzen wollt, danach die Realisierung und später die Auswertung. Interessant waren auch die Auflistung von Fehlschlägen und deren Untersuchungen; viele denken Fehlschläge seien etwas peinliches aber irren ist nun mal menschlich.

Soviel zu einem Fachbereich bei dem man gerade mal zwei Stunden die Woche Vorlesungen in Pascal hatte.

Aber ich denke auch das es im Bereich der Informatik (oder wie die Fachrichtungen heute alle so heißen) doch interesanter ist welche grundsätzlichen Dinge hinter den Programmzeilen stecken.

Heute arbeite ich auch im Bereich der Software-Entwicklung und kann hier aus Erfahrung sagen das ich mehr Zeit vor dem Whiteboard in meinem Büro verbringe wie vor meiner Workstation. Und meinen Leuten kann ich auch nur sagen: Erst grübeln, dann dübeln (Im weitesten Sinne).

Gruß,
Karsten