Wie genau muss eine DOKU sein?

[trodana]

Hallo Leute, muss bei der Dokumentation wirklich alles haargenau beschrieben sein.

Beispiel Betriebssystem installieren: zunächst wird die cd eingelegt, anschließend die bootreihenfolge...

[Chief Wiggum]

Wirst du Installationsmeister, dass du sowas abliefern willst?

Standardumfang der Doku (Achtung, das variiert zwischen den verschiedenen Kammern!) liegt bei 10-15 Seiten plus Anhang.

Und es interessiert niemanden, auch nicht die Prüfer, ob du nun einem Installationsassistenten folgen kannst oder nicht. In der Doku sollst du belegen, dass du fachlich qualifizierte Entscheidungen fällen kannst.

[trodana]

gut 12 seiten sind drin, alles andere ist nicht gut weil zu streng bewertet wird bei 15 seiten zb...

Nehmen wir mal an, wir schreiben eine Doku über einen Proxyserver,

Wie sieht die Realisierung aus?

Müssen die befehle zb in der config datei erklärt werden, bzw halt zb um den proxyport zu setzen muss folgender befehl hinzugefgt werden : ....?

die realisierung muss ja alles haargenau enthalten, wie etwas durchgeführt wurde..und die config datei ist ja von nöten, damit der proxyserver überhaupt einmal funktioniert....

ist es ratsam die doku wirklich so aufzubauen? oder sollte man den kompletten code lieber auslagern in den anhang und nur das nötigste in die realisierung mit reinpacken wie port authentifizierung zb...

[MartinSt]

Ja genau und da der Rechner auch angeschaltet werden muß, ist beim Menschen der das tut, eine Koordination zwischen Finger, Auge und Hirn erforderlich. Ich erwarte da als Prüfer zumindest eine kurze Darstellung der zugrundeliegenden kognitiv-neuronalen Prozesse, wobei ich nur über 50% der möglichen Punkte gebe, wenn mindestens eine neuronale Disfunktion näher betrachtet wird ... aber eben maximal auf 15 Seiten.

//ironie=off

[Chief Wiggum]

In die Doku gehören grundlegende technische und kaufmännische Entscheidungen, warum ein Proxy (und wenn dann welcher) die richtige Lösung für ein Problem ist. In die Doku gehören die Entscheidungen, welche Techniken genutzt werden.

In einer Doku haben Installationsanleitungen nichts zu suchen. Etwaige Konfig-Dateien kann man in den Anhang verfrachten.

[geloescht_Symbolio]

So wie Chief Wiggum das erläutert wurde es mir auch erklärt. Deshalb halte ich meine pers. Doku auch recht kurz und knackig und "outsource" alles in den Anhang, wie Installation und Konfiguration.

Die Doku soll mehr einen Überblick verschaffen, was getätigt wurde, welche Entscheidungen getroffen wurden usw. usf.

Zudem ist es Übersichtlicher und man kommt nicht schon in der Doku vom hunderstel ins tausendstel. Da verliert sich einiges und ich glaube kaum das sich das noch einer komplett durchliest. Nimm dir ein Beispiel an Programmdokumentationen oder Betriebssystemdokumentation (wie die von Linux Distribution o.ä.), diese sind i.d.R. recht klar strukturiert: Thema, Inhaltsverzeichnis, kurze Erläuterung zum Thema und dann die jeweiligen Abschnitte zu bestimmten Bereichen. Diese werden meist in einem 3-4 Zeiler erklärt und dann wird auf Installations- oder Konfigurationsseiten verwiesen.

[sportsocke]

Halte dir einfach folgendes vor Augen:

Jmd externes, der nur die Doku liest, sollte verstehen was du gemacht hast und warum du gewisse Schritte gegangen bist.

Dabei kannste ein gewissen Tiefe vorraussetzen. Sachen, an denen du Zweifel hast, solltest du als Glossar anhängen.

(z.B. Installationsroutine, die nähere Anmerkung benötigt)

Hierbei gilt zu beachten (zumindest ist es bei unserer ihk so) dass man 12-15 seiten doku + max. 15. sinnvollen Anhang nicht überschreitet sollte.

Das einfachste bei It Berufen die Sinnhaftigkeit der Dokumentation zu überprüfen ist es, die Doku deiner Ma in die Hände zu drücken

Wenn sie versteht (nicht technisch) was du als Projekt machst und warum, dann weisst du, dass deine Doku schonmal eine gewisse Logik aufweist - dies ist , zumindest für mich, immer eine relative große Hilfe

Bearbeitet 21. September 2009 von sportsocke

[geloescht_Symbolio]

Hierbei gilt zu beachten (zumindest ist es bei unserer ihk so) dass man 12-15 seiten doku + max. 15. sinnvollen Anhang nicht überschreitet sollte.

15 Seiten sinnvollen Anhang :confused:

Pro Software habe ich vllt. 15 Seiten sinnvollen Anhang, aber nicht alles zusammen auf 15 Seiten. Das schaffe ich auch niemals, da ich fast alles an Installation+Konfiguration in den Anhang "outsourcen" muss, sonst sprengt es allemal die 15 Seiten Doku.

Zuviel an Anhang-Seiten sollte man nicht haben, sehe ich ein. Aber 15 Seiten Anhang ist etwas dürftig. Erstrecht wenn man im Linux Bereich viel auf manuell macht.