Allgemeine Fragen zur Dokumentation meiner Projektarbeit

[Neo van Matix]

Hallo,

meine Projektarbeit beschreibt das Thema des Monitorings von firmeninternen Servern. Im Rahmen dessen habe ich mich nicht im Vorfeld auf ein Produkt wie etwa Nagios festgelegt, sondern eine Marktanalyse dieser Tools eingebunden.

Das Produkt, das sich durch Recherche am besten mit den während der Dokumentation definierten Anforderungen / dem Soll-Zustand deckt, soll im Netzwerk implementiert werden.

Nun habe ich einige allgemeine Fragen, die ich noch nicht beantworten konnte.

1) Da im Vorfeld kein Produkt, um das sich ein Großteil der Dokumentation dreht, feststand, haben sich rückwirkend natürlich auch die Gliederungspunkte oder Begebenheiten geändert, welche im Projektantrag festgelegt wurden. Z.b. hatte ich dort mit eingebracht, dass ich einen Dienst-Testserver zum Test-Monitoring aufsetzen wollte - da das zum einen ... uneffektiv ist, zum anderen auch nichtmal Ansatzweise die Möglichkeiten der von mir ausgesuchten Monitoringlösung ausschöpft, habe ich in Übereinstimmung mit der Geschäftsführung diesen Punkt über Bord geworfen und plane / implementiere die Monitoringlösung direkt in den Produktiveinsatz.

Ich habe - nach bestem Gewissen - unter meinem Überpunkt "Projektplanung" einen Punkt "Geänderte Arbeitspakete" eingefügt, in dem ich diese Situation schildere - das ich z.b. die ursprünglich geplante Erstellung eines Testservers aus genannten Gründen ausgeschlossen, und den direkten Einsatz im Produktivnetz umsetze.

Meine Frage: Genügt dies? Wie detailliert muss ich Änderungen beschreiben? Muss ich das überhaupt?

2) Ich sprenge bereits jetzt "leicht" meine Dokumentation - allein durch die Definition von Projektumfeld, Projektvorfeld (Marktanalyse, IST/SOLL, etc.) und Projektplanung (Zeitplanung, Geänderte Projekte), der Auswahl eines Betriebssystems, etc. - komme ich auf 7 Seiten, und habe noch nicht einmal die Installation des Monitoring-Dienstes, noch der Konfiguration, etc. beschrieben. Ich kann das zwar noch etwas kaschieren (Zeilenabstand auf 1 Setzen) und womöglich später auch kürzen, aber um das Auslagern in Aushänge werde ich nicht herum kommen.

Meine Frage: Kann ich so einen Punkt wie die Installation des Betriebssystems, auf dem später der Monitoringdienst installiert und konfiguriert wird, in einen Anhang auslagern? Meine Präsentation dreht sich primär um die Implementierung der MOnitoringlösung - meines Erachtens nach spielt die Installation des Betriebssystems (Klicke hier, dort das eingeben, ...) eine stark nebensächliche Rolle und ist auch in keinem Fall als anspruchsvolle Herausforderung, noch als "qualitativer Bonuspunkt" anzusehen.

Meine Frage 2: Gibt es so etwas wie eine Richtlinie, WAS ausgelagert werden darf, und was nicht?

3) Nochmal zu den Anhängen...

Meine Frage: In welcher Zeitform soll man diese Erstellen? In "HowTo"-Form - das heißt, "Für die Installation von Debian 4 auf einem xyz müssen Sie das Iso in das virtuelle CDRom-Laufwerk einbinden, ..." oder in der "Ich habe das so und so gemacht"-Form: "Das Iso-Image von Debian 4 wurde für die Installation in das virtuelle CDRom-Laufwerk eingebunden".

4) Das wurde sicher schon öfter gefragt, aber wo ich gerade dabei bin... Welchen Seitenrahmen sollte ich bei den Anhängen einhalten? Ich schätze, 30 ist akzeptabel?

5) Nun zu einer etwas interessanteren Frage... ich habe während der Installation der VMware-Tools auf ein kurzes HowTo zurückgegriffen, dass ich vor mehreren Wochen/Monaten auf meiner privaten Website veröffentlicht habe. Ich bin zwar der Autor des Artikels - jedoch wurde der Artikel nicht innerhalb der Projektarbeit erstellt, noch diese "Recherche" betrieben. MUSS ich diesen Artikel, von dem ich selbst der Autor bin, als Quellenangabe angeben?!

Vielen Dank für eure Hilfe!

[Capricious]

Auf qualifizierte Antworten bin ich auch gespannt. Ich halte zwar die Projektphasen ein aber die Struktur innerhalb ist anders tituliert. Aus meiner Sicht geht das auch nicht anders, weil ALLES kann man nun beim Antrag nicht absehen. Ich hoffe doch, ich muss da nicht jede Titeländerung begründen solange die Bedeutung dahinter gleich geblieben ist?

Ansonsten bin ich gespannt auf die Antwort mit der Installationbeschreibung. Ich finde die 15 Seiten verdammt eng bemessen. Ich selbst bin dabei alles in die Kundendokumentation zu implementieren. Den interessiert es ja letzendlich was ich da getan habe und wir er selbst die Software erweitern kann. Gerade wenn man kein Projekt hat, was Konsolenlastig ist, wirds haarig. Und ich beschränk mich schon auf das Wichtigste.

Und selbst dann sind 15 Seiten eng .

Ich würde an deiner Stelle sowas simples wie OS Installation komplett weglassen. Es sei denn, da wird irgendwas super spannendes eingestellt. Und selbst dann reicht da ein Screenshot oder kurze Anmerkung.

Ich freu mich jetzt schon auf die 5 MB pdf Begrenzung.

Bearbeitet 11. April 2009 von Capricious

[Neo van Matix]

Ich würde an deiner Stelle sowas simples wie OS Installation komplett weglassen. Es sei denn, da wird irgendwas super spannendes eingestellt. Und selbst dann reicht da ein Screenshot oder kurze Anmerkung.

Ich freu mich jetzt schon auf die 5 MB pdf Begrenzung.

Hm - diese "Installation" ist aber doch Teil der Arbeit? Ich meine... klar wird da nix spannendes erklärt - aber ich kanns ja nicht voraussetzen, dass der Prüfer weiß, wie man ein Debian aufsetzt. Ebenso könnte ich ja sagen ich lass die Installation der Monitoringlösung weg, weil die Prüfer sooft mit Nagios und Co konfrontiert werden, dass sie's bereits kennen und eine weitere erwähnung überflüssig wäre...

[charmanta]

Wohaaaa ... ne Menge Fragen für nen Feiertag.

Mal kurz zusammen gefasst:

Mach Dir keine Sorgen. Entweder der PA weiss, wie man UNIX installiert oder er wird Dich fragen.

zu 1) Begründete (!!!) Änderungen des Projektablaufs werden einfach nur dokumentiert. So wie Du das beschreibst ist das ok. Stell Dich darauf ein, daß vom PA im Zweifel Rückfragen kommen oder erklär das gleich bei der Präsi.

zu 2) Pack alles, was man als "Blender" werten könnte in den Anhang. Vor allem alles, was mit der Projektidee als solcher nicht den kompletten Bezug hat. Grafiken, Bilder, Tabellen, Installationsanleitungen können in den Anhang. Aber nur dann, wenn sie halt grösser als sagen wir mal 1/3 Seite sind. Es gibt dafür keine Regeln ( wie in der Praxis ) .... der Gesamteindruck muss stimmen. Es gibt auch kein Limit für den Anhang, keine Sorge ( das ist zu 4) )

zu 3) Dammichnochmal. Würdet Ihr ernsthaft in einem Projekt für einen Kunden die Ich-Form benutzen ????? Aufwachen. KEINE Ich-Form.

Ihr bildet eine Kundensituation ab und macht das dann auch bitte professionell. :upps

zu 5) Nö. Ist keine externe Quelle. Du kannst eher in der Präsi erwähnen, daß Du durch das Projekt auf die Idee dazu gekommen bist.

So nun ab und schick die Eier suchen lassen

[Capricious]

Danke Charmanta, und glaub mir, ich würde meine Feiertage auch gerne anders verbringen .

[Neo van Matix]

zu 3) Dammichnochmal. Würdet Ihr ernsthaft in einem Projekt für einen Kunden die Ich-Form benutzen ????? Aufwachen. KEINE Ich-Form.

Ihr bildet eine Kundensituation ab und macht das dann auch bitte professionell. :upps

Das ich da nicht "ICH"-Form verwende ist mir klar, nur mir ist nichts besseres für das Beispiel eingefallen -.- Konkrete Situation:

Zuerst generiert man einen MD5-Hash des gewünschten Passworts, z.b. auf der Kommandozeile des Zabbix-Servers:

monmil26:/# echo -n „Passwort“ | md5sum

Dann öffnet man den MySQL-Interpreter und verbindet sich mit der Zabbix-Datenbank:

monmil26:/# mysql

Welcome to the MySQL monitor. Commands end with ; or \g.

Your MySQL connection id is 334

Präsenz - Gegenwart. Richtig, oder falsch? Dokumentiere ich, was ich gemacht HABE, oder wie jemand, der das ganze nachvollziehen will, vorgehen SOLL? Das der obige Wortlaut suboptimal ist und sich bescheiden anhört, weiß ich - habe ich in einer späteren Fassung auch entsprechend angepasst. Aber es passt als Beispiel grad recht gut...

Die Alternative in der Vergangenheit:

Ein neues Passwort wurde durch einen MD5-Hash auf der Kommandozeile des Zabbix-Servers generiert:

[charmanta]

Das ist ein Prima Beispiel:

Genau der Mustersatz liest sich wie ein Teil einer Klickorgie bzw. Installationsanleitung und das ist NICHT der richtige Text für eine Arbeit.

Ob nun im Gegenwartsform oder in der Vergangenheit spielt keine Rolle.

Ich persönlich bervorzuge die Gegenwartsform.

[Neo van Matix]

Das ist ein Prima Beispiel:

Genau der Mustersatz liest sich wie ein Teil einer Klickorgie bzw. Installationsanleitung und das ist NICHT der richtige Text für eine Arbeit.

Ob nun im Gegenwartsform oder in der Vergangenheit spielt keine Rolle.

Ich persönlich bervorzuge die Gegenwartsform.

Naja, aber wenn ich einen Vorgang beschreibe - zu Dokumentationszwecken und zur Nachvollziehung - dann komm ich nicht drum rum, in der Art zu schreiben:

Müssen die Pakete xyz installiert werden:

apt-get install ...

Zusätzlich muss die Datei xyz editiert, und der Paramter x durch y getauscht werden

vi ...

Wie soll ichs den sonst machen? Einfach auf "die Manual des Produkts" verweisen und mich "aus dem Schneider verkriechen" ?!

[charmanta]

Professionell denken: einen Kunden interessieren auch keine Kommandos, nur die Info, warum das überhaupt nötig ist. Wenn er dann nen Hinweis auf einen Exkurs im Anhang findet und das DA drin steht passts doch :mod:

[Neo van Matix]

Hm.. in dem Bereich, in dem ich zuständig bin, gibts in dem Sinne keine "Kunden", weshalb ich da kein wirkliches Gefühl für hab.

Aber ja, ansich.. wäre es mir auch lieb, den ganzen uninteressanten so-wurde-es-gemacht-Kram in einen Anhang auszulagern.

Ich frage mich dann nur, was von meiner Projektarbeit als qualitativ zu bewerten übrig bleibt. Beispiel: Mein Thema "Monitoringlösung für firmeninterne Server" besteht aus einer Marktanalyse, nem IST-Soll-Zustand und natürlich ner Implementierung des aus gegebenen Gründen bevorzugten Tools.

Für eine Implementierung gehört für mich:

- Abwägen von Anforderungen wie Hardware, Software, Infrastruktur

- Die Installation eines Hosts für den Dienst, und dann natürlich auch die Installation des Servers

- Die Installation div. Agents auf Servern, die überwacht werden sollen

- Das Einrichten von entsprechenden Überprüfungen der zu überwachenden Servern

Wenn ich das alles "beschneide" - heißt, "Wie werden die Agents installiert", etc. in Anhänge auslager, komm ich mit nem 1,5er Zeilenabstand sicher auf meine 10 Seiten Doku - aber imho steht in diesen 10 Seiten dann nichts wirklich "qualitatives" drinnen, weil ich zum großteil nur auf Anhänge referenzier. Oder muss ich das garnicht?

Beispiel:

5.1 Installation des Betriebssystems

Als Betriebssystemgrundlage wurde die Linux-Distribution Debian gewählt. Da dessen Installation keinen besonderen Stellenwert in dieser Dokumentation einnimmt, wurden die bei der Installation getätigten Schritte und getroffenen Konfigurationseinstellungen in den Anhang „Installation des Betriebssystems“ ausgelagert.

Wenn soetwas 3-4 x vorkommt, findest du das dann als Prüfer nicht ... "komisch"? Natürlich wurde zuvor beschrieben, WESHALB debian eingesetzt wird.

[charmanta]

das Installieren und Einrichten interessiert den PA reichlich wenig. VIEL wichtiger ist, ob Du ne Idee hast, was Du da tust und warum.

Ob Du nun "abc -x" oder "-y" tippst ist Banane.

Welche Parameter überwachst Du wie und warum. Was passiert bei Schwellwertüberschreitung, welche Maßnahmen werden ergriffen. DAS ist interessant.

Ich muss mich leider kurz halten, da ich nicht weiss, ob Deine Arbeit schon abgegeben wurde. Bitte nicht böse sein :floet:

[Neo van Matix]

Naja, wenn Sie schon abgegeben wurde, würde ich ja aktuell keine Probleme bei der Gliederung und Formulierung haben, oder?

Ist natürlich einleuchtend.. ich sollte meinen Fokus wieder auf die eigentliche Sache des Monitorings richten und mich nich mit Belanglosigkeiten wie der Installation aufhalten...

[Soldiar]

Hallo,

wollte nur mal fragen, ob es möglich ist im Anschluss die Projektarbeit auch zu bekommen, da ich bisher nur Erweiterungen für Nagios geschrieben habe, und an einer solchen Dokumentation wie deiner sehr interressiert wäre. Wäre schön, wenn du dich via PN melden würdest

Vielen Dank vorab.

Mfg,

Christian, 20, K.