Dokumentation als A-Handbuch vs. Dokumentation als A-Checkliste

Ich habe in der Vergangenheit mit anderen Mitarbeitern meiner Abteilung über die Dokumentation, insbesondere den Detaillierungsgrad und die Anforderungen gesprochen. Ihrer Ansicht nach ist die Dokumentation eine einfache Checkliste von Y Maßnahmen, wenn X Probleme auftreten.

Ich stimme dir nicht zu. Ich denke, dass dies voraussetzt, dass alle Probleme in der IT leicht auf einfache Checklisten von Wiederherstellungsverfahren reduziert werden können. Ich denke, das ignoriert die Komplexität der Situation völlig und da die anderen Mitarbeiter in der Abteilung nicht immer ein tiefes Verständnis für das Problem haben (weshalb ich das Dokument schreibe - sie haben also etwas, worauf sie sich beziehen können) ), dass die Dokumentation einige grundlegende Hintergrundinformationen enthalten sollte, wie z.

• Zweck des betreffenden (Teil-) Systems
• Warum ist es so konfiguriert
• Erwartungen an Ereignisse, die auftreten werden, wenn die Einstellungen / Prozeduren implementiert werden
• Mögliche Probleme, die zum Fehlschlagen von Verfahren führen können

Allerdings bin ich eher auf diese überstimmt, so meine Dokumentation erforderlich neu geschrieben in eine Form zu sein , die sagt , „Schritte ABC angewendet wird , um Problem X zu lösen“. Ich höre oft die Klage, dass es auf eine einzelne Papierseite passen muss. Erklären Sie die Konfiguration von Squid-ACLs auf diese Weise, einschließlich der Fehlerbehebung, anhand eines einseitigen Dokuments. Dies ist nur eines von einem halben Dutzend Dokumenten, die darauf warten, als Wiederherstellungs-Checklisten geschrieben zu werden.

Geht die von mir vorgeschlagene Methode wirklich über Bord? Oder haben sie recht, und ich sollte mich hier nur um meine Angelegenheiten kümmern und ihnen einfach eine einfache Checkliste schreiben? Ich mache mir Sorgen, dass unabhängig davon, wie gut Sie eine Prozedur-Checkliste schreiben, ein Problem, bei dem ein SysAdmin überlegen muss, nicht gelöst wird. Wenn Sie Zeit damit verbringen, eine Checkliste mit Wiederherstellungsverfahren zu erstellen, die das Problem letztendlich nicht beheben (da es aufgrund des engen Fokus des Dokuments zusätzliche Faktoren gibt, die nicht Teil des Dokuments sind ), und den Zweck der Das Dokument sollte vermeiden, Manpages, Wikis und Websites immer wieder neu zu lesen. Warum gehe ich dann die Anträge durch? Mache ich mir nur zu viele Sorgen, oder ist das ein echtes Problem?

BEARBEITEN:

Derzeit gibt es keine Helpdesk-Stelle in der Abteilung. Das Publikum für die Dokumentation wäre für die anderen Administratoren oder für den Abteilungsleiter.

Beim Schreiben meiner habe ich immer zwei drei Sätze geschrieben. Die Checkliste zum Durchstarten mit einem VIEL VERLÄNGERTEN Anhang über die Architektur des Systems, einschließlich der Frage, warum die Dinge so gemacht werden, wie sie sind, wahrscheinlichen Knackpunkten beim Online-Gehen und abstrakten Entwurfsannahmen. gefolgt von einer Liste möglicher Probleme und ihrer Behebung, gefolgt von einem längeren Abschnitt mit Informationen über die Funktionsweise eines Systems und warum dies so ist, sowie weiteren Informationen, die hilfreich sind, um Menschen in die richtige Richtung zu weisen, falls etwas Einzigartiges passiert.

Bei meinem letzten Job mussten wir ein Dokument schreiben, damit selbst Helpdesk-Mitarbeiter der Stufe 1 die Dinge wieder auf den neuesten Stand bringen konnten. Dies erforderte Checklisten, die in der Regel innerhalb von 3 Monaten nach dem Schreiben veraltet waren. Wir wurden dringend gebeten, nach Möglichkeit Fehlerbehebungshandbücher zu schreiben. Wenn der Notfallbaum jedoch mehr als drei Zweige enthält, können Sie dieses Dokument nur schreiben, wenn Sie abstrakt werden.

Als ich meinen letzten Job verlassen habe, habe ich ein 100-seitiges Handbuch zur Erledigung meines Jobs durchgesehen, bevor ich gegangen bin. Es enthielt das Abstrakte, die Designphilosophie sowie Integrationspunkte. Da ich vermutlich für einen anderen Sysadmin schrieb, der mich ersetzen würde, richtete ich mich an jemanden, der abstrakte Vorstellungen aufgreifen und sie in konkrete Handlungen umsetzen konnte.

Fünf Jahre sind vergangen und ich finde, dass sich meine Meinung dazu etwas geändert hat. Sowohl Dokument als Handbuch als auch Dokument als Checkliste haben sehr wertvolle Stellen in der Dokumentationshierarchie und müssen beide erstellt werden. Sie richten sich jedoch an sehr unterschiedliche Zielgruppen.

Dokument als Checkliste

Der Zielmarkt für diese Art von Dokumentation sind Mitarbeiter, die wissen möchten, wie etwas zu tun ist. Sie kommen in zwei Arten:

• Mitarbeiter, die nur wissen wollen, wie man etwas macht und keine Zeit haben, ein fünfzehnseitiges Handbuch durchzublättern und die Schritte selbst herauszufinden.
• Prozeduren, die in Schritten ziemlich komplex sind, aber nur gelegentlich ausgeführt werden müssen.

Ungeduld ist der Treiber für die erste Art. Vielleicht möchte Ihr Kollege gar nicht wissen, warum die Ausgabe über eine Perl-Regex mit 90 Zeichen geleitet werden muss, nur um das Ticket zu schließen. Nehmen Sie auf jeden Fall eine Aussage wie "Eine ausführliche Erklärung, warum dieser Workflow so aussieht, finden Sie unter diesem Link" in die Checkliste für diejenigen, die wissen möchten, warum.

Der zweite Punkt betrifft Prozeduren, die nicht häufig ausgeführt werden, aber Fallstricke enthalten. Die Checkliste fungiert als Karte, um das sichere Schicksal zu vermeiden, sie nur zu beflügeln. Wenn die Checkliste in einem Dokumentations-Repository aufbewahrt wird, muss die E-Mail nicht nach der Zeit durchsucht werden, in der der alte Administrator ein HOWTO gesendet hat.

Meiner Meinung nach enthält eine gute Checklistendokumentation auch Abschnitte über mögliche Fehlerquellen und Antworten auf diese Fehler. Dies kann das Dokument ziemlich umfangreich machen und TL; DR-Antworten bei Mitarbeitern auslösen. Daher ist es meines Erachtens ein Unscary-Checkliste, wenn die Fehlermodi und ihre Antworten als Link von der Checkliste anstatt von der Seite selbst verwendet werden. Umfassen Sie Hypertextualität.

Dokument als Handbuch

Der Zielmarkt für diese Art von Dokumentation sind Menschen, die mehr über die Funktionsweise eines Systems erfahren möchten. Die Dokumentation zur Vorgehensweise sollte sich aus dieser Dokumentation ableiten lassen. Ich sehe sie jedoch häufiger als Ergänzung zur Dokumentation im Checklistenstil, um die im Workflow getroffenen Entscheidungen zu sichern.

Dies ist die Dokumentation, in der wir solche zähen Stücke wie enthalten:

• Erklären, warum es so konfiguriert ist.
  • Dieser Abschnitt enthält möglicherweise nicht-technische Themen wie die Politik, wie das Ganze gekauft und installiert wurde.
• Erklären der häufigsten Fehlermodi und ihrer Antworten.
• Erläutern von schriftlichen und tatsächlichen Service-Level-Agreements.
  • De facto: "Wenn dies während der Finalwoche fehlschlägt, ist es ein Problem, bei dem alles verloren geht. Wenn Sie während der Sommerpause schlafen gehen und sich morgens darum kümmern."
• Festlegung von Upgrade- und Refactoring-Zielen.
  • Die Politik mag später anders sein, warum korrigieren wir nicht einige der schlechten Ideen, die am Anfang eingeführt wurden?

Diese sind alle sehr nützlich, um ein umfassendes Verständnis des gesamten Systems zu erlangen. Sie brauchen kein umfassendes Verständnis, um einfache Aufgaben der menschlichen Automatisierung auszuführen. Sie müssen herausfinden, warum etwas so schief gelaufen ist, und eine Idee haben, wo Sie es dazu bringen können, dies nicht noch einmal zu tun.

Sie haben auch die Disaster Recovery-Dokumentation erwähnt, bei der es sich um eine Checkliste handeln muss.

Ich verstehe, Sie haben mein Mitgefühl.

Ja, die DR-Dokumentation muss so checklistenartig wie möglich sein.
Ja, DR-Dokumentation ist am widerstandsfähigsten gegen Checklisten, da sie auf viele Arten beschädigt werden kann.

Wenn Ihre DR-Checkliste so aussieht:

1. Ruf Dustin oder Karen an.
2. Erklären Sie das Problem.
3. Treten Sie zurück.

Du hast ein Problem. Das ist keine Checkliste, das ist ein Eingeständnis, dass die Wiederherstellung dieses Systems so komplex ist, dass ein Architekt das herausfinden muss. Manchmal ist das alles, was Sie tun können, aber versuchen Sie es zu vermeiden, wenn es überhaupt möglich ist.

Idealerweise enthält die DR-Dokumentation Verfahrensprüflisten für einige verschiedene Dinge:

• Triage-Prozeduren, um herauszufinden, was schief gelaufen ist und um ...
• Wiederherstellungsverfahren für bestimmte Fehlerfälle. Welches wird unterstützt von ...
• Wiederherstellungsskripte, die gut im Voraus geschrieben wurden, um menschliche Fehler während der Wiederherstellung zu minimieren.
• Manuelle Dokumentation über die Fehlerfälle, warum sie auftreten und was sie bedeuten.

Triage-Prozeduren sind manchmal die gesamte DR-Dokumentation, die Sie für einige Systeme erstellen können. Wenn dies jedoch der Fall ist, wird der Anruf um 4 Uhr morgens verständlicher und der leitende Ingenieur, der die Wiederherstellung durchführt, kann das eigentliche Problem schneller lösen.

Einige Fehlerfälle haben einfache Wiederherstellungsverfahren. Dokumentieren Sie sie. Während der Dokumentation finden Sie möglicherweise Fälle, in denen Befehlslisten in einer bestimmten Reihenfolge eingegeben werden. Dies ist ein hervorragender Anwendungsfall für die Skripterstellung. Es kann ein 96-Punkte-Wiederherstellungsverfahren in ein 20-Punkte-Verfahren verwandeln. Sie werden nie herausfinden, ob Sie etwas skripten können, bis Sie die Wiederherstellungsprozedur Aktion für Aktion zuordnen.

Die manuelle Dokumentation für Fehlerfälle ist die letzte Rücklaufsperre, die verwendet wird, wenn keine Wiederherstellungsprozeduren vorhanden sind oder die Wiederherstellungsprozeduren fehlgeschlagen sind. Es bietet die erforderlichen Google-Hinweise, um möglicherweise jemanden zu finden, der dieses Problem hatte, und was er getan hat, um es zu beheben.

Eigentlich verwenden wir auch nicht Documentation As-a-Testcase

Davon abgesehen haben wir eine Dokumentation geschrieben, die zur Dokumentation als Handbuch gehört . Wir hatten Checklisten eingerichtet, aber als wir gewachsen sind, stellten wir fest, dass diese fehleranfällig waren und auf dem gesamten System wirklich versagten.

Wir haben jedoch eine Art "Documentation As-a-Checklist" installiert, das heißt, wir überwachen - wie oben erwähnt - unsere Dienstleistungen ausgiebig. Es gibt ein Sprichwort:

Wenn Sie es nicht überwachen, verwalten Sie es nicht

Das ist so absolut wahr, aber ein anderer sollte sein:

Wenn Sie es nicht überwachen, dokumentieren Sie es nicht

Wann immer wir Services migrieren müssen, behalten wir einfach die "Service Group", "Host Group", bei, was auch immer gilt (wir verwenden Nagios, wie Sie aus dem Vokabular erraten können) und es wird nicht migriert, solange es einen einzelnen roten Punkt gibt auf einem der Dienste.

Die Tests bieten eine viel bessere Checkliste als jede handgeschriebene Checkliste. Es ist eigentlich selbstdokumentierend, sobald wir einen Fehler haben, der noch nicht überwacht wurde, wird der Test zumindest zu Nagios hinzugefügt, mit dem wir 2 Dinge kostenlos bekommen:

• Wir wissen, wann es fehlschlägt
• Ein weiterer Punkt auf der Checkliste

Die "echte" Dokumentation befindet sich in einem Wiki, in dem die Chancen und Ziele des jeweiligen Dienstes oder Tests aufgeführt sind. Wenn es fehlt, werden die Leute es hinzufügen, sobald wir eine Migration durchführen oder damit arbeiten müssen. Bisher hat dieser Ansatz sehr gut funktioniert.

Auch fehlerhafte Dokumentationen werden sehr schnell ausgebügelt. Immer wenn etwas nicht funktioniert, wird nachgeschlagen und versucht, das Problem mit den darin enthaltenen HowTos zu beheben. Wenn es falsch ist, aktualisieren Sie es einfach mit Ihren Ergebnissen.

Denken Sie nur an die Fehler, die möglicherweise entstehen könnten, wenn Sie einer Checkliste folgen und keine Tests installiert haben, die Ihnen nach dem Anwenden ein grünes Kontrollkästchen anzeigen. Ich denke nicht, dass es möglich ist, die Dokumentation von der Überwachung zu trennen.

Es hängt von der Zielgruppe Ihrer Dokumentation ab.

Für Helpdesk-Typen (Stufe 1) ist eine Checkliste der richtige Weg. Dies setzt natürlich voraus, dass es ein höheres Maß an Unterstützung für das von Ihnen beschriebene tiefere Wissen gibt.

Wenn die Dokumentation für die Systemgruppe ist, irre ich mich immer auf der Seite der Dokumentation. Es ist schon schwer genug, über eine ausreichende Dokumentation zu verfügen, wenn jemand (Sie) umfangreichere Dokumente mit den erforderlichen Hintergrundinformationen schreiben möchte - kein vernünftiger Mensch sollte Ihnen im Weg stehen!

Persönlich versuche ich, die Dokumentation so einfach wie möglich zu halten. Es umfasst in der Regel:

• Was [X] tun soll (Anforderungen).
• Wie [X] auf hohem Niveau strukturiert wurde (Design).
• Warum ich [X] so implementiert habe, wie ich es getan habe (Überlegungen zur Implementierung).
• Wie die Implementierung von [X] nicht dem Standard entspricht (Problemumgehungen).
• Häufige Probleme mit [X] und deren Behebung (Probleme).

Zugegebenermaßen handelt es sich in meinem Abschnitt zu allgemeinen Problemen wahrscheinlich um eine kurze Beschreibung der Vorgänge und um exemplarische Vorgehensweisen zur Fehlerbehebung.

Ich gehe normalerweise von Kenntnissen des Lesers des betreffenden Systems aus (es sei denn, es ist besonders geheimnisvoll). Ich habe keine Zeit, meine technische Dokumentation auf Stufe 1 oder das Management lesbar zu machen - aber eine Hinweisstufe 3 sollte in Ordnung sein.

Ich denke, das hängt natürlich vom Thema ab. Nicht alles lässt sich auf eine einfache Checkliste reduzieren, und nicht alles benötigt eine ausführliche Bedienungsanleitung.

Es hört sich sicher so an, als würden Sie von interner Dokumentation sprechen, und meiner Erfahrung nach können Sie nicht einfach eine Liste von Schritten angeben, da es zu viele Möglichkeiten gibt. Sogar das Erstellen eines Benutzerkontos bietet einige Optionen (in unserer Umgebung), sodass in unserem Dokument "Neues Konto" die grundlegenden Schritte in der angegebenen Reihenfolge aufgelistet werden. Für jeden Schritt wird jedoch eine Beschreibung der Variationen angezeigt.

Auf der anderen Seite haben wir nie viel von einem Dokument für "How to patch in a office" geschrieben, aber unser sehr skizzenhaftes Dokument war auch keine Checkliste - es erwähnte die Konvention, die wir für die Farben von Kabeln verwendeten, betont dass Sie die Tabelle aktualisieren mussten, in der die Verbindungen aufgeführt sind, und das war es auch schon.

Jetzt, da ich das geschrieben habe, stimme ich voll und ganz zu: Schritt-für-Schritt-Checklisten sind für viele Prozesse einfach nicht ausreichend.

Ich stimme Ihnen sehr zu (zugunsten einer umfassenden Dokumentation), da ich es gewohnt bin, Vorgänger zu haben, die überhaupt kein großes Interesse an Dokumenten hatten. Wie bereits in ähnlichen Beiträgen erwähnt, ist das Ausschreiben nicht nur für andere von Vorteil, sondern hilft Ihnen auch dabei, Ihre Umgebung besser zu verstehen und sie in Ihrem eigenen Kopf zu festigen . Es ist ein Selbstzweck.

Abgesehen davon stelle ich fest, dass ein Großteil des Pushbacks auf der seltsamen Annahme beruht, dass beschissene / nicht vorhandene Dokumentation = Arbeitsplatzsicherheit. Diese Art des Denkens scheint einfach unehrlich und zwielichtig.

Ein großes Lob an Sie, dass Sie sich gegen den Status Quo gewehrt haben.

Ich dokumentiere ziemlich viel, ich habe sogar eine Checkliste für die Dokumentpriorität :-), aber ich werde keine Dinge dokumentieren, die als Allgemeinwissen gelten können (dh eine vernünftige gute Beschreibung des Problems gibt eine Antwort auf die erste Seite von Google).

Für alle Interessierten ist hier meine doc prio Checkliste (funktioniert für mich, möglicherweise nicht für Sie, Kommentare und Vorschläge werden sehr geschätzt):

1. Erstellen Sie ein persönliches Tagebuch, in dem Sie alles aufschreiben, was Sie getan haben
2. Services, welcher Service ist wo, was macht er und für wen wird er erbracht (irgendwelche SLA-Vereinbarungen? Sollte eine erstellt werden?)
3. Server, welcher Server ist wo, wie alt und wann ist er geschrieben
4. Wie oben, jedoch für Netzwerkgeräte, UPS und dergleichen
5. Wie oben, jedoch für alle Benutzergeräte
6. Aufbau des physikalischen Netzwerks (welches Kabel führt wohin, wie lang ist es und welche Qualität wird gemessen)
7. Konfigurationsübersicht über Software und Lizenzen für Server
8. Konfigurationsübersicht über Software und Lizenzen für Benutzercomputer
9. Konfigurationsübersicht über Switches, Router und andere dedizierte Hardware
10. Verträge und SLA aller externen Parteien, von denen mein Service direkt abhängt (ISP, Domain etc.)
11. Richten Sie ein Ticketsystem mit integriertem Wiki ein, um alle oben genannten Dinge darin abzulegen.
12. Erstellen Sie für jeden Vorfall ein Ticket (auch wenn Sie es nur für sich selbst verwenden).
13. Erstellen Sie ein Skript, das am Sonntag Tickets sammelt und diese nach Problemtyp gruppiert.
14. Erstellen Sie am Montag eine automatische Lösung oder ein Endbenutzer-Howto-Dokument für das am häufigsten auftretende Problem
15. Wenn es die Zeit erlaubt, mach das nächste.
16. Wenn nichts mehr zu tun ist, suche einen neuen Job und gib der Person, die dich ersetzt, das Protokoll ;-)

Eine Checkliste ist in Ordnung, solange sie nicht vorgibt, eine vollständige Dokumentation zu sein. Die letzten Dokumente, die ich geschrieben habe, bestanden aus zwei Teilen: XYZ für Benutzer, die hübsche Screenshots zur Verwendung enthielten; und XYZ für Systemadministratoren, einschließlich der Art und Weise der Einrichtung und der Gründe (möglicherweise sogar einschließlich der Geschäftsanforderungen), zu vermeidender Traps und eines Abschnitts zur Fehlerbehebung. Bei der Fehlerbehebung werden voraussichtlich die Checklisten angezeigt. Vielleicht hilft es, die Checklisten als XYZ für den technischen Support zu schreiben.

Wenn ich nun zwischen den Zeilen lese und mich nur auf Checklisten konzentriere, sehe ich einen Mangel an "Big Picture" -Denken und langfristiger Planung, den ich von jemandem erwarten würde, der: nur technischen Support geleistet hat; oder ein Junior-Administrator, der gerade erst anfängt; oder ist so überfüllt mit Arbeit, dass sie keine Zeit haben, darüber nachzudenken; oder wurde nie dazu gedrängt, darüber nachzudenken; oder einfach egal. Ich weiß nicht, welche davon in Ihrem Fall zutreffen.

Ich bin ziemlich stark in der Dokumentation. Die Firma, in der ich jetzt arbeite, ist der Meinung, dass Dokumentation wichtig ist, aber einige Leute in der Firma haben das Gefühl, dass sie keine Zeit haben, Dokumentation zu schreiben. Dies kann jedem das Leben schwer machen, außer der Person, die es ursprünglich getan hat.

Für bestimmte Dinge habe ich eine Schritt-für-Schritt-Anleitung geschrieben. Sie können dies eine Checkliste nennen, wenn Sie möchten, aber es ist nicht wirklich dazu gedacht, physisch abgehakt zu werden. Ich bezeichne meinen Dokumentationsstil als "Kindergartenschritte". Es ist nach einem MCSE-Heft aufgebaut, das ich für eine der Windows 2000-Prüfungen hatte. Die Schritte sind sehr detailliert, aber die Verwendung von Fett / Kursiv / Schrift erleichtert das Beschönigen und Auswählen der wichtigen Teile, sodass Sie nach dem Erlernen der Schritte nicht mehr alles lesen müssen.

Einige Dinge eignen sich nicht für schrittweise Anleitungen, daher versuche ich, so viele Konfigurationsdaten wie möglich bereitzustellen. Einige technisch veranlagte Personen, die am Ende auf der Straße bleiben, werden eine bessere Vorstellung davon haben, worauf sie stoßen, und hoffentlich wird dies ihr Leben ein wenig erleichtern, wenn etwas schief geht.