Fragen zur Doku

[Gromsy]

Mein Projekt wurde nun ohne Auflagen genehmigt, und ich mache mir immer mehr Gedanken darum, unter Anderem um die Dokumentation. Die Dokumentation soll an unterrichtende Dozenten und die Administration der Umgebung gerichtet sein (gehört das eigentlich in der Doku erwähnt?).

Mein Projekt hat mit Virtualisierung zu tun. Ich habe Fragen zum Aufbau der Doku, da ich ja nun bald mit der Aufnahme von Soll- und Ist-Zustand sowie der Projektplanung beginnen will.

Dabei interessiert mich speziell der Anhang. Zunächst einmal zum Glossar.

Ich überlege, den Anhang so zu gestalten, dass er verschiedene Indices hat. Einer davon soll unter Anderem der Glossar sein. In meinem Projekt tauchen zweifelsohne Begriffe auf wie:

- Hypervisor

- Virtuelle Maschine

- Virtual Machine Monitor

- Bare Metal VMM

- API

- ...

Gehören solche Begrifflichkeiten erläutert? wie ausführlich soll so etwas sein sprich, genügt ein kurzer, aussagekräftiger Satz über den Begriff oder verlangt der PA fundiertes Basiswissen, sprich dass sie nicht nur eine Definition, sondern auch Funktionalität und den Zweck erläutert bekommen? Ich nehme an auf Dinge wie den Betriebssystemkernel oder das Vom-Neumann-Prinzip muss ich nicht genauer eingehen?!

Meine Aufgabe ist es u. A., mögliche Virtualisierungssoftware unter bestimmten gesichtspunkten zu evaluieren. Dabei müssen wahrscheinlich Nachweise erbracht werden, bspw. wenn ich von einem Programm behaupte, es sei kostenlos. Ich habe überlegt, dafür direkt aus dem Lizenzvertrag zu zitieren und/oder Screenshots aus der Produktbeschreibung des Entwicklers mit einzufügen.

Ich habe mir überlegt, dazu den Index Quellen mit anzuhängen, diese durchzunummieren und im Dokumentationstext darauf zu verweisen. Dabei will ich dann das Zitat zu diesem Thema mit anbringen und auf die Originalseite verlinken. Ist dies die beste Herangehensweise?

Welche der folgenden Dokumente kann ich außerdem in den Anhang auslagern, welche gehören zwingend in die Doku:

- Netzwerkplan

- Nutzwertanalyse

- Wirtschaftlichkeitsanalyse

Unter welcher Rubrik der Dokumentation soll die Softwareevaluation stattfinden? Ein extra Unterpunkt der Projektplanung?

Vielen Dank für jegliche Hilfe .

Bearbeitet 27. August 2008 von Gromsy

[Cheris]

Ich würde an deiner Stelle einmal ein paar Dokus die es im Internet gibt, anschauen um ein wenig das Gefühl dafür zu bekommen, wie diese aufgebaut sind.

Zum ersten richtet sich die Projektdokumentation an den IHK-Prüfungsausschuss. Lediglich die Kundendokumentation richtet sich an eine spezielle Gruppe. In diese musst du dann auch auf jeden Fall zu Beginn reinschreiben, für wen diese Kundendokumentation gedacht ist. Projektdokumentation und Kundendokumentation sind zwei unterschiedliche Paar Schuhe.

Zum Glossar reicht gewöhnlich ein bis zwei Sätze. Schau dir am besten mal ein Glossar in einem Buch an, da wird auch nicht ausführlich erklärt.

[flashpixx]

Hallo,

im Grunde kannst Du alles in den Anhang packen bzw alles in die Doku. Ich denke eine gesunde Mischung macht es. Wenn ich die Doku lese, dann sollte ich den "roten Faden" finden und auch anhand von Diagrammen o.ä. dieser Faden erläutert werden. Details z.B. exakte Aufschlüsselung der Netzwerkkonfiguration, Datenbankdiagramme, Produktdatenblätter usw. gehören in den Anhang, da ich diese dann wenn ich es genau wissen will, nachschlagen kann.

Ich denke ein Index oder Glossar ist etwas viel für eine Projektdoku. Der PA ist ja vom Fach und wird sich in den entsprechenden Themen auskennen. Die Kundendoku sei jetzt einmal außen vor. Vielleicht als Hilfestellung: Wenn Du selbst die Doku liest, dann solltest Du im Kopf noch einmal die ganze Arbeit durch gehen können, Schwierigkeiten müssen zu erkennen, die Lösungsmöglichkeiten usw. Wenn Du z.B. in der Doku schreibst "aufgrund der XXXX Ergebnisse wird dieses oder jenes Produkt eingesetzt", dann reicht das, wenn Du das jetzt z.B. von den Kosten im Detail aufschlüsselst, würde ich es in den Anhang nehmen.

HTH Phil

[Gromsy]

Das hat mir schon sehr geholfen. Nehmen wir also an ich will die Software anhand einer Nutzwertanalyse evaluieren: Verlangt der Prüfungsausschuss eine Erklärung von mir, wieso ich bestimmte Produkte mit der entsprechenden Punktzahl bewertet habe? wie sieht es mit der Beschreibung von Software aus - sollte ich erwähnen, worin sich die einzelnen Lösungen unterscheiden? Ich meine wenn ich z. B. einer Software dafür, dass sie kostenlos ist und keine zusätzliche Hardware benötigt volle Punktzahl beim Kostenaufwand gebe, will der Prüfungsausschuss vorher kurz über das Produkt informiert werden oder langt es, wenn ich den Lizenzvertrag und ein Produktblatt an den Anhang tackere und die entsprechende Stelle, die mir die kostenlose Nutzung und die geringen Hardwareanforderungen versichert, markiere?

Bearbeitet 28. August 2008 von Gromsy

[stev4n]

Im grunde ganz einfach. Gib die Doku jemanden der sich damit überhaupt nicht auskennt und all dies was er nicht kennt, erläutern im Glossar.

Warum du wie was bewertest hast gehört rein bzw. warum du dich für das Produkt entschieden hast ob ausführlich oder nicht musst du selbst wissen.

Bei meiner Dolu war dies ein entscheidender Punkt mit why ich mich für diese Software entschieden habe und war deshalb bei mir ausführlich.

[1pruefer]

Ich denke ein Index oder Glossar ist etwas viel für eine Projektdoku. Der PA ist ja vom Fach und wird sich in den entsprechenden Themen auskennen.

Falsch gedacht!

Zu den formalen Prüfkriterien in unserem Bewertungsformular gehört ein Punkt "Inhaltsübersicht mit Seitenangaben", wenn der Index also fehlt, dann stehen hier definitv 0 Punkte.

Unter dem Bewertungskriterium "Kundendokumentation / kundengerechte Anfertigung, Zusammenstellung, Modifikation" erwarte ich - üblicherweise als ersten Punkt - im, bzw vor dem, Anhang ein Glossar. Meine Kollegen denken auch so.

Wegen der Breite der IT kann man auch nicht davon ausgehen, dass jedes PA-Mitglied über alles in der IT Bescheid wissen kann. Auch Prüfer haben in ihrem Berufsleben sehr wahrscheinlich Spezialgebiete.

Mir bspw sagt Hypervisor etwas, aber auch jedem BS-Lehrer, der in einen PA abgeordnet worden ist?

[flashpixx]

Zu den formalen Prüfkriterien in unserem Bewertungsformular gehört ein Punkt "Inhaltsübersicht mit Seitenangaben", wenn der Index also fehlt, dann stehen hier definitv 0 Punkte.

Ein Index ist etwas anderes als ein Inhaltsverzeichnis. Siehe hierzu Register (Nachschlagewerk ? Wikipedia))

Unter dem Bewertungskriterium "Kundendokumentation / kundengerechte Anfertigung, Zusammenstellung, Modifikation" erwarte ich - üblicherweise als ersten Punkt - im, bzw vor dem, Anhang ein Glossar. Meine Kollegen denken auch so.

Bei einer Kundendoku macht dies durchaus Sinn, aber der Projektdoku würde ich das nicht zwingend erwarten

Wegen der Breite der IT kann man auch nicht davon ausgehen, dass jedes PA-Mitglied über alles in der IT Bescheid wissen kann. Auch Prüfer haben in ihrem Berufsleben sehr wahrscheinlich Spezialgebiete.

Mir bspw sagt Hypervisor etwas, aber auch jedem BS-Lehrer, der in einen PA abgeordnet worden ist?

Ich hatte in meiner Doku keinen Glossar, den zwei Sachen, die ich ausführen musste, waren als Fußnoten angegeben. In meinen wissenschaftlichen Arbeiten an der Uni gehört ein Glossar ab einem Gewissen Umfang, genauso wie ein Index, dazu. Da aber durch die IHK ja oft eine maximale Seitenzahl vorgegeben wird, ist natürlich auch der Umfang für einen Index / Glossar begrenzt. Ich würde für 3 oder 4 Begriffe keinen Index oder Glossar anlegen.

HTH Phil

Bearbeitet 29. August 2008 von flashpixx
Link war nicht korrekt

[Gromsy]

naja flashpixx der Glossar, das Inhaltsverzeichnis und insgesamt der gesamte anhang mit Deckblatt wird - afaik - nicht beachtet wenn es zum Auszählen der seitenzahlen kommt. Das heißt man kann ihn rein theoretisch in einem angemessenen Rahmen ruhig in einige Seiten ausarten lassen.

danke schonmal für Alles, ich hoffe wenn ich irgendwann auf weitere Fragen stoßen sollte kann ich es hier nochmal versuchen . bis dahin sind alle Fragen soweit geklärt.