Erste Schritte mit der Dokumentation

An meinem Arbeitsplatz haben wir keine Dokumentation durchgeführt. Ich bin völlig neu darin und bitte um eine Anleitung zum Einstieg.

Ich habe ein paar Fragen:

• Was sind die wesentlichen Dokumente, die ein Systemadministrator schreiben und verwalten sollte? Und warum sind diese so wichtig?

• Wie halten Sie Ihre Dokumentation mit dem System synchron? Wie minimieren Sie Doppelarbeit?

• Empfohlene Anleitungen, Best Practices, Anti-Patterns?

seit 2003 dokumentiere ich alles in unserem hauseigenen wiki.

Server

• Hardware-Spezifikationen
• Garantieinformationen
• Netzwerkinformationen
• und natürlich installierte Software und Konfiguration

Arbeitsabläufe

zB wie man einen Benutzer hinzufügt oder löscht und ihm Zugang zu allen relevanten Diensten gewährt

Wichtige links

• Link zu allen Ihren Web-Oberflächen
• Link zu den Monitoring-URLs (Nagios, Munin, Apc-Monitoring ...)
• Link zum Wiki (für die gedruckte Version!)

Notfallanweisungen

Was tun, wenn Intranetserver / Internet / Webserver / etc ausgefallen sind?

Wichtig:

Wählen Sie eine Wiki-Engine mit einfachem Export nach PDF!
Es ist nicht nützlich, wenn Sie im Urlaub sind, der Server, auf dem Ihr Wiki ausgeführt wird, nicht verfügbar ist und niemand weiß, was zu tun ist, da Ihre Dokumentation offline ist

Schauen Sie sich twiki, docuwiki oder mediawiki an.

Übrigens:

Es gibt ein OpenOffice.org-Plugin , mit dem Sie direkt in MediaWiki schreiben können - sehr praktisch.

BEARBEITEN:

Es ist auch schön, ein paar Infos zu schreiben /home/adminuser/maintenance. Dies ist schnell erledigt und kann sehr hilfreich sein, wenn mehrere Administratoren auf einem Server arbeiten. z.B:

2009-06-27 -thorsten-
          running aptitude update && aptitude full-upgrade
          everything seems ok
2009-06-25 -andreas-
          cups-pdf wasn't reachable. restarted cups
2009-06-23 -thorsten-
          deleted old log under /var/log/squid
etc.

Während Sie erkennen, dass jeder Dokumentation haben will (und braucht), müssen Sie auch erkennen, dass niemand Zeit hat, diese zu lesen und zu studieren.

Schreiben Sie also keine Dokumentation, die untersucht werden muss, sondern strukturieren Sie Ihre Dokumentation so, dass jemand die benötigten Informationen schnell finden kann, wenn er sie benötigt - was durchaus möglich ist, wenn das System und der CTO nicht in Betrieb sind seinen / ihren Nacken hinunteratmen.

In diesem Sinne einige Vorschläge ...

• Vermeiden Sie große Textblöcke
• Aufzählungszeichen sind dein Freund
• Ein klares Diagramm ist golden
• Wiederholung ist eine gute Idee (1)
• Machen Sie es einfach zu aktualisieren und zu erweitern

(1) Erschaffe keine einzige Quelle der Wahrheit und zwinge die Menschen, sie zu finden. Je wichtiger die Idee, desto mehr sollten Sie sie wiederholen.

Wichtige Dokumente:

• Serverdokumentation - Spezifikationen / Festplattenlayouts / installierte Software / alles Wichtige
• Gängige Verfahren - Wenn etwas getan wird, das nicht „trivial“ ist, sollte ein Verfahren dokumentiert werden, insbesondere, wenn es etwas ist, das zuvor noch nicht getan wurde.

Das Synchronisieren der Dokumentation kann so ziemlich das Problem beheben, wenn Sie Fehler sehen. Dazu gehört die Erkenntnis, dass die Dokumentation veraltet sein kann und wird und nicht blindlings befolgt werden sollte, ohne dies zu berücksichtigen. Die Dokumentation soll einen Administrator bei Aufgaben unterstützen, nicht bei der schrittweisen Festlegung von Regeln, die das kritische Denken ersetzen.

Minimierung von Duplikaten - wenn Sie Wikis verwenden, in denen Sie Dokumentation miteinander verknüpfen können, können Sie hier Abhilfe schaffen. Statt Informationen zu wiederholen, müssen Sie nur darauf verweisen. Das Problem ist, dass die Person, die die Dokumentation erstellt, wissen muss, dass die zu duplizierenden Informationen bereits vorhanden sind. Dies ist in der Regel eine Frage guter Organisation.

Ich habe festgestellt, dass das Erstellen einer Vorlage eine große Hilfe ist. In meinem Fall handelt es sich um eine Word-Vorlage, Sie können jedoch jede Suite verwenden. Erstellen Sie eine Skelettdatei mit den gewünschten Feldern und Abschnitten für das Inhaltsverzeichnis. Wenn Sie es ein paarmal verwendet und Feinabstimmungen vorgenommen haben, können Sie neue Dokumente viel schneller erstellen. Die Konsistenz des Formats ist sowohl für die Dokumentenerstellung als auch für die spätere Verwendung eine große Hilfe. Die Dokumentation muss an einem logischen Ort und in einer logischen Verzeichnisstruktur gespeichert werden.

Ich persönlich bin gegen die Wiederholung der einfachen Tatsache, dass es unnötig schwierig und zeitaufwändig ist, sie zu warten. Erstellen Sie gegebenenfalls Verweise auf andere Dokumente, anstatt Dokumente oder Dokumententeile zu duplizieren. Wenn sich etwas ändert , sollten Sie nie dann , wenn die entsprechenden Unterlagen mehr ändern müssen oder in mehr als einem Ort, sonst Sie werden eine Sammlung von widersprüchlichen Dokumente haben, die niemand hilft.

Denken Sie beim Erstellen Ihrer Dokumentation immer daran, wofür diese bestimmt ist. Jemand zu einem späteren Zeitpunkt muss es verwenden. Kann der Job ohne Vorkenntnisse ausgeführt werden?

Keine direkte Antwort auf Ihre Frage, sondern ein Hinweis in die richtige Richtung:

Ich fand die Praxis der System- und Netzwerkadministration von Limoncelli und Hogan (auch bekannt als die Sysadmin-Bibel) sehr wertvoll, da es sich um "Best-Practice" -Probleme handelt, wie zum Beispiel um Dokumentation. Wenn Sie es noch nicht wissen, sollten Sie es untersuchen, wann immer Sie die Chance dazu haben.

Die wichtigste Überlegung ist für mich, die Bedienung zu vereinfachen. Wenn es schwierig ist zu orchestrieren, werden die Leute es vermeiden. Ich wähle aus folgenden Gründen das Wiki von Trac als Medium für unsere Dokumentation:

• Zentral gelegen.

  Mehr als eine aktive Kopie eines Dokuments führt zu Verwirrung. Wenn Sie alle an denselben Ort verweisen können, sowohl die Mitwirkenden als auch die Zuhörer, können Sie den Prozess vereinfachen.

• Einfaches Bearbeiten und Formatieren.

  So viel Zeit wird mit hübschen Word-Vorlagen und der Anpassung an das Styling des letzten Autors verschwendet. Wenn Sie die Leute damit nicht im Stich lassen, ist es einfacher, sie unterwegs zu bearbeiten, und die Mitwirkenden neigen eher dazu, dies zu tun. Trennen Sie Elemente mit TracLinks nach Belieben.

• Prüfhistorie.

  Es ist wichtig zu wissen, wer welche Änderung wann und warum vorgenommen hat. Wenn Sie es mit Tickets für Änderungsanforderungen und Konfigurations-Commit-Protokollen verknüpfen können, ist es sogar noch besser. SVN-Commit-Hooks sind dafür großartig.