Frage Erste Schritte mit der Dokumentation


Wir haben an meinem Arbeitsplatz keine Dokumentation gemacht. Ich bin völlig neu dazu und bitte um ein paar Tipps.

Ich habe ein paar Fragen:

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

  • Wie halten Sie Ihre Dokumentation mit dem System synchron? Wie minimieren Sie die Duplizierung von Informationen?

  • Empfohlene Anleitungen, Best Practices, Anti-Patterns?


20
2017-07-27 00:52


Ursprung


Verbunden: Wie dokumentieren Sie ein Netzwerk? - Zoredache


Antworten:


seit 2003 dokumentiere ich alles in unserem hauseigenen Wiki.

Server

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

Arbeitsabläufe

z.B. wie man einen Benutzer hinzufügt oder löscht und ihm Zugang zu allen relevanten Diensten gibt

Wichtige Links

  • Link zu allen Ihren Web-Schnittstellen
  • Link zu den Überwachungs-URLs (Nagios, Munin, APC-Monitoring ...)
  • Link zum Wiki (für die gedruckte Version!)

Notfallanweisungen

was zu tun ist, wenn Intranet-Server / Internet / Web-Server / etc heruntergefahren sind

Wichtig:

Wähle eine Wiki-Engine mit einfachem PDF-Export!
Es ist nicht nützlich, wenn Sie im Urlaub sind, der Server, auf dem Ihr Wiki läuft, ist inaktiv und niemand weiß, was zu tun ist, weil Ihre Dokumentation offline ist

Schau dir twiki, docuwiki oder mediawiki an.

BTW:

da ist ein OpenOffice.org Plugin direkt in mediawiki schreiben - 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.

15



+1 für den Fallback-Hinweis, wenn das Wiki nicht verfügbar ist. - Manuel Faux
Was ist OOo? Sieht aus wie OpenOffice, aber ich kann das letzte "o" nicht herausfinden. Wenn Sie das Plugin benennen könnten, wäre es großartig. - Daniel C. Sobral
Richtig, OOo ist OpenOffice.org ;-) Die Erweiterung: extensions.services.openoffice.org/de/project/wikipublisher - ThorstenS


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

Schreiben Sie also keine Dokumentation, die untersucht werden muss, sondern strukturieren Sie Ihre Dokumentation so, dass sie schnell die benötigten Informationen finden kann, wenn sie benötigt werden. Dies kann auch der Fall sein, wenn das System nicht aktiv ist und der CTO vorhanden ist seinen Hals hinunter atmen.

In diesem Sinne einige Vorschläge ...

  • Vermeiden Sie große Textblöcke
  • Bullet-Listen sind dein Freund
  • Ein klares Diagramm ist golden
  • Wiederholung ist eine gute Idee (1)
  • Erleichtern Sie das Aktualisieren und Erweitern

(1) Nicht erstellen ein Quelle der Wahrheit und zwingen die Menschen, es zu jagen. Je wichtiger die Idee ist, desto mehr sollten Sie sie wiederholen.


13



Bei mehr als einer Dokumentationsquelle gibt es jedoch mehrere Orte, die aktualisiert werden müssen, wenn sie veraltet sind und geändert werden müssen. Ein guter Weg um dies (wenn Sie ein Wiki oder etwas Ähnliches haben) ist zu versuchen, eine wahre Quelle der Wahrheit zu machen und von so vielen Orten wie nötig mit ihr in Verbindung zu treten. - Mark
In gewissem Maße stimme ich zu - Links und Querverweise können in der Tat sehr nützlich sein. Es gibt jedoch einen Kompromiss: Beim Datenbankdesign ist es üblich, Tabellen zu dementifizieren, um die Berichterstellung zu unterstützen. Ich denke, der gleiche Ansatz ist hier relevant - zu machen Verbrauch der Dokumentation einfacher, kann die Wiederholung wichtiger Fakten wertvoll sein. - Bevan
Es ist in Ordnung, Prinzipien weit zu verbreiten, aber für Dinge wie IP-Adressen, Passwörter, Konfigurationsmanagement eine zentrale autorisierende Quelle von Daten zu zentralisieren, mit angemessenen Backups ist der Schlüssel zur vernünftigen Verwaltung. - Tom H
Ich würde zustimmen - solange es beides ist sehr bekannt und leicht zugänglich - eine einzige Autorität Geheimnis Quelle ist eine allzu häufige Antipattern. - Bevan
Ich stimme der Wiederholung nicht vehement zu, denn man wird aktualisiert, andere nicht. Oder sie werden inkonsistent aktualisiert. Stattdessen sollten die wichtigeren Dokumente leichter zugänglich sein verlinkt. - gWaldo


Wesentliche Dokumente:

  • Serverdokumentation - Spezifikationen / Festplattenlayouts / installierte Software / alles, was zu beachten ist
  • Allgemeine Verfahren - alles, was nicht "trivial" ist, sollte eine dokumentierte Prozedur haben, besonders wenn es etwas ist, was vorher nicht gemacht wurde.

Dokumentation synchron zu halten kann eine "Fehler beheben, wie Sie Fehler sehen" -Affäre. Dazu muss die Erkenntnis kommen, dass die Dokumentation veraltet sein kann und wird und dass sie nicht blind befolgt werden sollte, ohne dies zu berücksichtigen. Dokumentation ist da, um einem Administrator bei Aufgaben zu helfen, und nicht eine Schritt für Schritt Regelwerk zu sein, das kritisches Denken ersetzt.

Minimierung von Duplikaten - Verwenden Sie so etwas wie Wikis, wo Sie die Dokumentation miteinander verknüpfen können. Dies kann helfen, anstatt die Informationen zu wiederholen, sondern einfach nur darauf verlinken. Das Problem besteht darin, dass die Person, die die Dokumentation erstellt, wissen muss, dass die Informationen, die sie duplizieren möchten, bereits vorhanden sind. Dies ist normalerweise eine Frage der guten Organisation.


5





Ich habe festgestellt, dass das Erstellen einer Vorlage eine große Hilfe ist. In meinem Fall ist es eine Word-Vorlage, aber verwenden Sie, was auch immer Sie tun. Erstellen Sie eine Skelettdatei mit dem Feld "Inhaltsverzeichnis" und den gewünschten Abschnitten. Nachdem Sie es einige Male verwendet und Feineinstellungen vorgenommen haben, erstellen Sie viel schneller neue Dokumente. Die Konsistenz des Formats ist eine große Hilfe, sowohl für die Erstellung von Dokumenten als auch für die spätere Verwendung. Die Dokumentation muss an einem logischen Ort und in einer logischen Verzeichnisstruktur gespeichert werden.

Ich bin persönlich gegen Wiederholung wegen der einfachen Tatsache, dass es unnötigerweise schwierig und zeitaufwendig macht. Anstatt Dokumente oder Teile von Dokumenten zu duplizieren, erstellen Sie gegebenenfalls Verweise auf andere Dokumente. Wenn sich etwas ändert, sollten Sie die relevante Dokumentation nie mehr als einmal oder an mehr als einem Ort ändern, sonst Sie werden habe eine Sammlung von widersprüchlichen Dokumenten, die niemandem hilft.

Berücksichtigen Sie bei der Erstellung Ihrer Dokumentation, wofür sie gedacht ist. Jemand zu einem späteren Zeitpunkt wird es brauchen. Wird es verwendbar sein, um den Job ohne Vorkenntnisse zu erledigen?


4





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 (alias der Sysadmin Bible), um sehr wertvoll zu sein, weil es sich um "Best Practice" Probleme, wie Dokumentation, handelt. Wenn Sie es noch nicht wissen, stellen Sie sicher, dass Sie es untersuchen, wann immer Sie die Chance haben.


3



Die zweite Ausgabe dieses Buches enthält ein Kapitel zur Dokumentation. Ein verwandtes Buch mit dem Titel "Zeitmanagement für Systemadministratoren" enthält ein Kapitel zur Dokumentation, das sich mehr auf das konzentriert, was Sie tun müssen, als darauf, was Ihre Organisation tun muss. - TomOnTime


Die wichtigste Überlegung ist für mich die einfache Handhabung. Wenn es schwierig ist zu orchestrieren, werden die Leute es vermeiden. ich wähle Trac's Wiki als Medium für unsere Dokumentation aus diesen Gründen:

  • Zentral gelegen.

    Mehr als eine aktive Kopie eines Dokuments führt zu Verwirrung. Wenn Sie in der Lage sind, alle an denselben Ort, sowohl an die Mitwirkenden als auch an die Zielgruppe, zu verweisen, dann können Sie den Prozess vereinfachen.

  • Einfache Bearbeitung und Formatierung

    So viel Zeit wird für hübsche Word-Vorlagen verschwendet und entspricht dem Styling des letzten Autors. Wenn Sie die Leute damit nicht belästigen, ist es einfacher, unterwegs zu redigieren, und die Mitwirkenden neigen dazu, dies zu tun. Trennen Sie Gegenstände mit TracLinks so weit wie Sie möchten.

  • Prüfverlauf

    Es ist wichtig zu wissen, wer was wann und warum geändert hat. Wenn Sie es in Change Request Tickets und Konfigurations-Commit-Protokolle binden können, dann noch besser. SVN Commit Hooks sind dafür hervorragend geeignet.


0



Ich benutze auch trac für die Dokumentation eines Projekts. Was ist? Ja wirklich Missing ist eine Art Brotkrume im Wiki. Ich hoffe, das kommt bald. - ThorstenS