Allgemeines zur Dokumentation

meandor
Goto Top
Hey,

durch die Diskussion hier wurde ich mal wieder auf das Thema Dokumentation aufmerksam. Ich hab ein paar Postings hier gelesen und der Tenor war: "Dokumentation ist wichtig/erleichtert das Leben" bzw. "Dokumentation muss gemacht werden".

Es gibt aber wohl nicht wirklich Standards wie eine Dokumentation im Bereich einer Firmen-IT aussehen muss, oder?

Ich kann nur aus meinen eigenen Erfahrungen schöpfen.

In Firmen wo der Chef selbst der ITler ist, besteht die Dokumentation maximal aus einem Zettel auf dem diverse Passwörter notiert sind. Wobei die Chance hoch ist, dass die Passwörter inzwischen geändert sind und die aktuellen in einer Datei auf einem Netzlaufwerk oder in einem Cloudspeicher liegen.

Wird die IT von einem Mitarbeiter zusätzlich betreut, dann gibt es ein Netz-Share, da liegt meistens auch eine Textdatei mit den wichtigsten IP-Adressen, sowie mit Zugangsdaten und Passwörter. Ein Ausdruck der Datei liegt meist beim Chef und beim ITler im Schreibtisch.

Wurde das Netz von einem Systemhaus eingerichtet, steht irgendwo ein Ordner mit vielen Bildern und technischen Beschreibungen der Hardware und der Anbindung, sowie mit installierter Software und einer Liste auf der die Software mit Nutzerdaten und Passwörter vermerkt ist. Im Regelfall mit diversen Ergänzungen durch Bleistift oder Kugelschreiber.

Gibt es hauptberufliche Administratoren, dann sind auf deren Rechner meist Tools installiert mit den zumindest alles ohne Eingabe von Passwörtern administriert und verwaltet werden kann; aber irgendwo auf einem EDV-only Share liegt dann die Datei in der alle Passwörter und Zugangsdaten hinterlegt sind. Den Dokumentationsordner gibt es hier aber meist nur, wenn ein Systemhaus an der Einrichtung beteiligt war, und auf dem Stand ist der Ordner dann auch.

Je größer die IT-Abteilung, desto weniger finden wir Gesamtübersichten. Es hat dann zwar jeder noch Aufschriebe über gewisse Zugänge und Strukturen in seinem Arbeitsbereich, aber die sind nur so gepflegt wie der verantwortliche Admin Lust hat.

Gibt es evtl. imRahmen der Ausbildung zu einem der IT-Berufe irgendwelche Empfehlungen oder Vorlagen wie und was zu dokumentieren ist oder geht es wirklich nach dem Prinzip: "Wenn der Firmenchef nichts anweist, dann schreib ich mir nur auf, was ich brauche."

Klar, es gibt gesetzliche Vorgaben und Richtlinien, aber meine Erfahrung sagt, dass die in der Praxis eher eine untergeordnete Rolle spiele. Wo kein Prüfer, da keine Notwendigkeit der Umsetzung.

Content-Key: 2536538155

Url: https://administrator.de/contentid/2536538155

Ausgedruckt am: 03.07.2022 um 19:07 Uhr

Mitglied: altmetaller
altmetaller 19.04.2022 um 12:06:24 Uhr
Goto Top
Hallo,

wer zuviel dokumentiert, ist jederzeit austauschbar face-smile

Gruß,
Jörg
Mitglied: radiogugu
radiogugu 19.04.2022 aktualisiert um 12:13:31 Uhr
Goto Top
Hi.

Zitat von @altmetaller:
wer zuviel dokumentiert, ist jederzeit austauschbar face-smile

YMMD 🤣

Ich habe mir angewöhnt alles in ein NetBox System einzuklimpern. Ist anfangs jede Menge Arbeit so eine Doku, egal welches System an der Stelle. Doch die Vorteile liegen auf der Hand und sollten immer der Beweggrund sein, eine Doku zu erstellen.

Gerade, wenn man als zertifiziertes Unternehmen von einem Automobilisten mal in die Verlegenheit kommt in der IT auditiert zu werden, dann will man einfach nicht lange suchen und schnell zu den Infos kommen.

Leider geht das in der Ausbildung sträflich unter. Habe mehrere Praktikanten in die IT bezogenen Fachschulen bei mir gehabt, welche auf eben deine Frage (@TO) keine Antwort hatten oder eben sagten: "Ja, muss gemacht werden, weil wohl wichtig."

Gruß
Marc
Mitglied: em-pie
em-pie 19.04.2022 um 12:15:43 Uhr
Goto Top
Moin
Zitat von @altmetaller:
Hallo,
wer zuviel dokumentiert, ist jederzeit austauschbar face-smile
Gruß,
Jörg

Und wer zu wenig dokumentiert und aus gesundheitlichen Gründen längerfristig ausfällt, "schadet" dem Unternehmen. Von einer effizienten Fehlersuche mal ganz zuschweigen.

Das "gesunde" Mittelmaß ist sinnvoll face-smile
Bloß was ist gesund? face-big-smile

Gruß
em-pie
Mitglied: Meandor
Meandor 19.04.2022 um 12:24:01 Uhr
Goto Top
Zitat von @em-pie:
Und wer zu wenig dokumentiert und aus gesundheitlichen Gründen längerfristig ausfällt, "schadet" dem Unternehmen.

Die Diskussion hab ich mit meinem "Mit-Admin" gelegentlich; es geht dann aber um die "Tiefe" der Dokumentation. Wie viel Fachwissen kann man beim "Vertreter" voraussetzen, bzw. ab wann ist es "meine Schuld" wenn der Kollege mit meiner Doku nichts anfangen kann, weil sie zu viel voraussetzt?
Mitglied: radiogugu
radiogugu 19.04.2022 aktualisiert um 12:51:05 Uhr
Goto Top
Zitat von @Meandor:
Wie viel Fachwissen kann man beim "Vertreter" voraussetzen, bzw. ab wann ist es "meine Schuld" wenn der Kollege mit meiner Doku nichts anfangen kann, weil sie zu viel voraussetzt?

Das ist schon fast philosophisch.

Allerdings sollte ein "Mit-Admin", welcher dieselbe Infrastruktur betreut, auch einigermaßen denselben Stand haben.

Ansonsten ist es ja ein realistisches Szenario, dass ein externer Dienstleister einspringt, falls der hauseigene Admin nicht greifbar ist (Gründe erst einmal nachrangig).
Bei Diesem würde ich jetzt einfach mal voraussetzen, dass Fachwissen in ausreichendem Maß vorhanden ist.

Den Zugang zur Doku würde ich in jedem Fall bei der GF hinterlegen.

Gruß
Marc
Mitglied: clSchak
clSchak 19.04.2022 um 12:59:04 Uhr
Goto Top
Ich denke man muss einen Konsnes finden, was, wie und in wlechem Umfang dokumentiert werden soll. Wir nutzen für 99% der Fälle Tools die onPrem installiert sind und im WorstCase auch autark auf irgendeiner Hardware laufen können.

Die "tiefe" der Dokumentation hängt in den meisten Fallen am Service auf den es ankommt, ERP Dienste sind deutlich genauer und umfangreicher dokumentiert wie ein Printserver, ebenso ist die "Core" Hardware (SAN, VMWare Hosts, Router) genauer dokumentiert wird Edge Hardware, kommt immer auf dem Bedarfsfall an, einen roten Faden "das muss alles dokumentiert sein" gibt es so nicht, jeder hat andere Anforderungen.

Allerdings: lediglich die wichtigsten Admin-Kennwörter liegen auf "Papier" vor, in einem Tresor der GF, wird alle 6 Monat überprüft (versiegelter Umschlag) und ggf. erneuert. Der Rest ist nur Digital.

@altmetaller : 2-schneidges Schwert, wer zu wenig dokumentiert wird permanent, auch im Urlaub angerufen wenn etwas nicht geht face-wink - ich bin froh, dass wir mittlerweile einen recht guten Dokumentationsstand haben und ich im Urlaub nicht mehr angerufen werden, es sei denn, es fällt in meinem direkten Wirkungsbereich und ist etwas spezielles (sehr selten mittlerweile).
Mitglied: Doskias
Doskias 19.04.2022 um 13:03:03 Uhr
Goto Top
Moin,

Systemhäuser dokumentieren so genau, weil sie es müssen. Laut IHK (egal ob Abschlussprüfung oder Operativer Professional) gehört eine Dokumentation zu einem Projekt. Bei der Abschlussprüfung zum Fisi ist die Dokumentation mit 20 bis 25 % Zeit angesetzt. Bei einem einwöchigen Projekt, ist also 1 Tag für die Dokumentation vorgesehen. Warum ist dem so? Damit du nachweisen kannst, dass der Anforderungskatalog des Projektes umgesetzt wurde, denn nur wenn alle zehn Anforderungen erfüllt sind, kann ich als Systemhaus alle 10 Anforderungen abrechnen. Und ja, je länger das Projekt wird, desto länger wird ggf. die Dokumentation, wobei das Verhältnis dann von den 20% bis 25 % abweichen kann.

Das ist (aus meiner Erfahrung) ein Grund wieso Systemhäuser das machen. Der andere Grund ist: Sie wollen nicht noch dauernd irgendwelche Fragen haben, sondern sich anschließend dem nächsten Projekt widmen.

Leider geht das in der Ausbildung sträflich unter. Habe mehrere Praktikanten in die IT bezogenen Fachschulen bei mir gehabt, welche auf eben deine Frage (@TO) keine Antwort hatten oder eben sagten: "Ja, muss gemacht werden, weil wohl wichtig."
Das liegt dann leider oft an den Unternehmen. Wenn in der Abschlussprüfung eine Dokumentation erwähnt ist (was sie laut Prüfungsordnung sein muss), dann ist die Frage was und warum dokumentiert wurde als Prüfer legitim und einer meiner Kollegen stellt die Frage in jeder zweiten Prüfung. Vielen Prüflingen ist allerdings nicht mal bekannt, dass der Zeitfaktor "Dokumentation der Prüfung" die Kundendokumentation beinhaltet. Der Großteil meint, damit sei ihre eigene Dokumentation für die IHK gemeint, was definitiv nicht der fall ist.

Langer Anlauf zur Frage:
Die Diskussion hab ich mit meinem "Mit-Admin" gelegentlich; es geht dann aber um die "Tiefe" der Dokumentation. Wie viel Fachwissen kann man beim "Vertreter" voraussetzen, bzw. ab wann ist es "meine Schuld" wenn der Kollege mit meiner Doku nichts anfangen kann, weil sie zu viel voraussetzt?
Ich persönlich orientiere mich an den obigen Punkten.
Alles was ansatzweise einem Projekt nahe kommt wird dokumentiert und auf einem dafür bereitgestellten Ordner abgelegt. Beispiele: Einbau neues Bandlaufwerk, Umbau Firewall, Installation neuer Monitoring-Software, etc. Die hier dokumentierten Fakten sind oft statisch und ändern sich recht selten. Zum Beispiel die Startreihenfolge der VMs ändert sich dann doch eher selten.

Alles was dann eher in den Bereich "Linienaufgabe" fällt, also täglich gemacht wird und/oder sich in dynamischen Prozessen verändern kann, wird nicht dokumentiert, sondern mit den Kollegen kommuniziert. Dazu gehört dann zum Beispiel: Änderung von Backup-Zeiten, Benutzerberechtigungen via Gruppen, Zugriffsrechte auf andere Postfächer.
Wenn der Kollege zum Beispiel nicht in der Lage ist die Vertreterregeln im Exchange zu finden, dann hat er da nichts zu suchen. Wenn der Kollege nicht erkennt, dass das Backup fehlgeschlagen ist, weil die Sperrfrist am Bandlaufwerk noch nicht abgelaufen ist, dann soll er da nicht dran rumfummeln, sondern anrufen. Das sind Dinge, die sich durchweg häufig ändern können.

Es nützt deinem Mit-Admin sicherlich auch nichts wenn du nur noch Dokumentierst und nicht mehr administrierst face-wink

Gruß
Doskias
Mitglied: JoeToe
JoeToe 19.04.2022 um 13:48:20 Uhr
Goto Top
Moin.

@Doskias schrieb
Das ist (aus meiner Erfahrung) ein Grund wieso Systemhäuser das machen. Der andere Grund ist: Sie wollen nicht noch dauernd irgendwelche Fragen haben, sondern sich anschließend dem nächsten Projekt widmen.

Musste die Erfahrung machen, dass dem nicht immer so ist. Beispielsweise arbeitet ein Systemhaus kompetent und zuverlässig, auch ist es während der Supportzeiten gut erreichbar. Aber auf Rückfragen gibt man sich sehr zugeknöpft, beantwortet gern Fragen, die nicht gestellt wurden und rückt gezielt angefragte genauere Angaben nur ungern heraus. Da braucht man viel Geduld.
Ausführlich ist allenfalls der Wartungsvertrag.

Gruß
JoeToe
Mitglied: C.R.S.
C.R.S. 19.04.2022 um 15:55:36 Uhr
Goto Top
Zitat von @Meandor:

In Firmen wo der Chef selbst der ITler ist, besteht die Dokumentation maximal aus einem Zettel auf dem diverse Passwörter notiert sind.

Das möchte ich abstreiten. Selbst privat dokumentiere ich inzwischen recht konsequent, zumindest dichter als ich das in manchen Unternehmen vorfinde. Gerade in einer Doppelrolle ist es schlicht unmöglich sich zu merken, wie der ganze Kram funktioniert. Der Unternehmer kann es sich zeitlich auch nicht leisten, alle 18 Monate dieselben Fragen zu googeln, während es den angestellten Admins meist egal ist, zumal wenn andere Admins diesen Zeiteinsatz wiederholen.

Grüße
Richard
Mitglied: erikro
erikro 19.04.2022 um 19:23:49 Uhr
Goto Top
Moin,

eine Dokumentation ist so zu gestalten, dass ein fachkundiger Dritter sich innerhalb kurzer Zeit einarbeiten kann. Nicht mehr und nicht weniger. Die Haltung: "Wer zuviel dokumentiert, macht sich ersetzbar." ist nur insofern korrekt, als dass es genau darum beim Dokumentieren geht. Man muss im Unglücksfall ersetzbar sein. Es ist ziemlich egoistisch, das nicht zulassen zu wollen. Passiert einem mal was, steht gleich der ganze Betrieb still.

In die Doku gehört also jede Information, die wichtig ist, um den Betrieb am Laufen zu halten. Das fängt mit der (virtuellen) Hardware der Server an, geht über das eingesetzte Betriebssystem mit dokumentiertem Patchstand, den installierten Rollen, Feautures (oder vielleicht auch Services und Module face-wink ), deren Konfiguration usw. bis hin zur Dokumentation des Troubleshottings. Man kann nicht zu viel dokumentieren und dokumentiert immer zu wenig. face-wink

Eine gute Doku dient dem Wissenstransfer im Team und über die Zeit. Je größer Teams werden, desto spezialisierter werden die Aufgaben. Trotzdem sollte jeder im Team immer "wissen", was die anderen so machen. Da das aber so einfach nicht ist, legt man dieses Wissen in einer Doku ab, so dass jeder zumindest nachschlagen kann. Und über die Zeit deshalb, weil in einer guten Doku auch steht, was wie zu machen ist. Das fängt mit Nomenklaturen an und hört mit Installationsanweisungen auf. Letzters können dann auch Verweise nach außen sein.

Ich selbst bevorzuge Wikis. In meiner alten Firma wurde Confluence benutzt. Das ist richtig gut. In meiner neuen Firma musste ich feststellen, dass es keine ordentliche zentrale Doku gibt. Also auch Confluence ... Nein. Ich will weder in die Cloud mit meiner Doku noch so einen unverschämten Preis für die on-premise Version zahlen. Ich baue das jetzt mit wikimedia auf. Das funktioniert richtig gut. Ich mag vor allem deshalb Wikis, weil man über vernetzte Kategorien verschiedene Zugangswege schaffen kann. So gibt es die Kategorie "Server", in der alle sind, dann die Kategorien der Funktionen der Server, dann Sachkategorien usw. Und jeder Server ist in zwei bis vier Kategorien.

Das Wiki steht im internen Netz und ist so von jeder Arbeitsstation erreichbar, so dass man auch vor Ort darauf zugreifen kann und so nachlesen kann, was vor Ort Sache ist und auch gleich Änderungen dokumentiert. Die Dokumentation muss immer auf dem Laufenden sein. Ich persönlich habe die Doku immer auf, wenn ich irgendwas mache.

Kurz: Die Zeit, die man auf eine gute Doku verwendet, kriegt man an anderer Stelle mehr als zurück.

my 2 cents

Erik
Mitglied: maretz
maretz 19.04.2022 um 19:41:18 Uhr
Goto Top
Zum "Wer dokumentiert macht sich selbst ersetzbar" könnte man anmerken: Es kommt auch auf das WIE an. Ich mache z.B. viele Dokumentation in meiner Software - die daraus aber auch wieder automatisch Aufgaben für mich erledigt (z.B. mit den Daten aus dem Inventory hat man gleich die Möglichkeit zu prüfen ob Geräte da sind, DHCP-Server zu füttern,...). In sofern macht meine Dokumentation natürlich teile meines Jobs "ersetzbar" - was mir aber die Zeit gibt sinnvollere Dinge zu tun. Und Ersetzbar in sofern nicht das ja eben die Software auch jemand programmieren muss (wobei - bevor jetzt hier die ersten schreien das man ja dann auch wieder ne Abhänigkeit erschafft -> natürlich kann man auch problemlos die Daten exportieren, dann hat man auch z.B. das Inventory, muss dann halt die Tests wieder von Hand machen usw...)

Ist halt immer eine Frage des "Wie" - ich für mich habe halt entschieden sowas in ne Software zu packen die dann bei Bedarf die Doku in div. Formaten ausspucken kann. So hat der Betrieb immer die Möglichkeit wenn ich mal gehen sollte - und ich kann gleichzeitig mir meinen Tag von "Standard-Krams" grossteils freihalten.
Mitglied: altmetaller
altmetaller 20.04.2022 um 09:39:42 Uhr
Goto Top
Hallo,

Zitat von @maretz:

Zum "Wer dokumentiert macht sich selbst ersetzbar" könnte man anmerken: Es kommt auch auf das WIE an.

Stimmt - ich habe damals extra aramäisch und altgriechisch gelernt. Das ist viel besser als PGP face-smile

Gruß,
Jörg
Mitglied: Meandor
Meandor 21.04.2022 um 14:31:44 Uhr
Goto Top
Zitat von @radiogugu:

Zitat von @Meandor:
Wie viel Fachwissen kann man beim "Vertreter" voraussetzen, bzw. ab wann ist es "meine Schuld" wenn der Kollege mit meiner Doku nichts anfangen kann, weil sie zu viel voraussetzt?

Das ist schon fast philosophisch.

Allerdings sollte ein "Mit-Admin", welcher dieselbe Infrastruktur betreut, auch einigermaßen denselben Stand haben.


Gruß
Marc

Mein "Fall" ist, dass wir ein Team aus sechs spezialisierten, angelernten ITler sind. Damit wir unsere Arbeit zeitgemäß erledigen können, ist ein geschlossenes Netzwerk angefangen, dass von knapp 60 Personen genutzt wird und rund 80 Geräte enthält, darunter Storage-Server, DC, DC-Backup, WSUS, WDS-Server.

Ein Kollege war für den Ausbau maßgeblich verantwortlich, tritt aber auf Grund seiner eigentlichen Aufgaben kürzer. Der zweite Kollege hat sich inzwischen alles angeeignet um das Netz am Laufen zu halten (ich). Nur... Wenn irgendwas abschmiert, sind wir logischerweise beide nie da.

Die vier anderen Kollegen haben zumindest rudimentäre Kenntnisse von Windows-Server-Betriebssystemen und deren Rollen, aber eben keine tieferen. Sie können den Dienst oder notfalls den Server neu starten, aber dann ist es aus.

Ich kann zwar dokumentieren, welche Rolle auf welchem Server läuft, wie der heißt, ggf. was für Images oder GPO eingerichtet sind und warum, aber mehr geht ja eigentlich nicht. Ein Troubleshooting kann ich ja auch nur dokumentieren, wenn ich mich mit dem Fehler mal auseinandergesetzt habe, oder?
Mitglied: erikro
erikro 21.04.2022 um 19:27:29 Uhr
Goto Top
Moin,

Zitat von @Meandor:
Ein Kollege war für den Ausbau maßgeblich verantwortlich, tritt aber auf Grund seiner eigentlichen Aufgaben kürzer. Der zweite Kollege hat sich inzwischen alles angeeignet um das Netz am Laufen zu halten (ich). Nur... Wenn irgendwas abschmiert, sind wir logischerweise beide nie da.

Und deshalb braucht man eine gute Dokumentation.

Die vier anderen Kollegen haben zumindest rudimentäre Kenntnisse von Windows-Server-Betriebssystemen und deren Rollen, aber eben keine tieferen. Sie können den Dienst oder notfalls den Server neu starten, aber dann ist es aus.

Dann braucht man eine noch bessere Dokumentation.

Ich kann zwar dokumentieren, welche Rolle auf welchem Server läuft, wie der heißt, ggf. was für Images oder GPO eingerichtet sind und warum, aber mehr geht ja eigentlich nicht.

Da geht noch viel mehr. Gerade wenn es ein heterogenes Team ist, sind z. B. exakte Handlungsanweisungen sehr hilfreich. Zu einer guten Doku gehört auch das Desaster-Management. Was muss wann, wo gemacht werden? Wer ist zu verständigen (z. B. externe DL)? Usw. usf.

Ein Troubleshooting kann ich ja auch nur dokumentieren, wenn ich mich mit dem Fehler mal auseinandergesetzt habe, oder?

Das stimmt. Aber die User haben doch allzu oft immer wieder die gleichen Probleme. Ich kann und will mir einfach nicht merken müssen, was ich tun muss, wenn mal wieder ein ungeduldiger User fünfmal die gleiche umfangreiche Abfrage gestartet hat und deshalb die DB Schluckauf kriegt, oder wie man ein zickiges Add-In wieder in den Griff kriegt. Ich brauche meinen Kopf für wichtigere Dinge. face-wink

Ich schreibe das sofort auf, wenn mir mal was Neues unterkommt. Das ist extrem hilfreich, wenn mal wieder ein User anruft, während man gerade dabei ist, einen Fehler in einem hundertzeiligen Skript am suchen ist, und sofort bedient werden muss, weil er nicht mehr arbeiten kann. face-wink

Liebe Grüße

Erik