En écrivant le mien, je me suis toujours concentré sur l'écriture de deux trois sets. La liste de contrôle, avec une annexe BEAUCOUP PLUS LONGUE sur l'architecture du système, y compris pourquoi les choses sont faites comme elles sont, les points de blocage probables lors de la mise en ligne et les hypothèses de conception abstraite. suivi d'une liste des problèmes probables et de leurs résolutions, suivie d'une section plus longue avec des informations sur le fonctionnement d'un système, pourquoi il le fait ainsi et d'autres informations utiles pour orienter les gens dans la bonne direction si quelque chose d'unique se produisait.
Lors de mon dernier emploi, nous devions rédiger un document afin que même les personnes du niveau 1 du service d'assistance puissent reprendre les choses. Cela nécessitait des listes de contrôle, qui étaient généralement obsolètes dans les 3 mois suivant la rédaction. Nous avons été fortement encouragés à écrire des guides de dépannage dans la mesure du possible, mais lorsque l'arbre de contingence contient plus de trois branches, vous ne pouvez tout simplement pas écrire ce document sans devenir abstrait.
En quittant mon dernier emploi, j'ai retourné un manuel de 100 pages «Comment faire mon travail» avant de partir. Il contenait des éléments abstraits, une philosophie de conception, ainsi que des points d'intégration. Comme j'écrivais probablement pour un autre administrateur système qui allait me remplacer, je l'ai destiné à quelqu'un qui pouvait prendre des notions abstraites et les transformer en actions concrètes.
Cinq ans se sont écoulés et je trouve que mon opinion à ce sujet a quelque peu changé. Le document en tant que manuel et le document en tant que liste de contrôle occupent une place très précieuse dans la hiérarchie de la documentation et doivent tous deux être produits. Ils ciblent cependant des publics très différents.
Document comme liste de contrôle
Le marché cible pour ce type de documentation sont les collègues qui veulent savoir comment faire une chose. Ils existent en deux types:
- Des collègues qui veulent juste savoir comment faire quelque chose et qui n'ont pas le temps de feuilleter un manuel de quinze pages et de comprendre eux-mêmes les étapes.
- Procédures assez complexes par étapes, mais qui ne doivent être exécutées que de temps en temps.
L'impatience est le moteur du premier type. Peut-être que votre collègue ne veut pas vraiment savoir pourquoi la sortie doit être acheminée via une expression rationnelle perl de 90 caractères, juste que cela doit être pour fermer le ticket. Incluez certainement une déclaration du type «Pour une explication détaillée de la raison pour laquelle ce flux de travail ressemble à ceci, suivez ce lien» dans la liste de contrôle pour ceux qui veulent savoir pourquoi.
Le deuxième point concerne les procédures qui ne sont pas exécutées souvent mais qui contiennent des pièges. La liste de contrôle agit comme une carte pour éviter le Certain Doom de simplement l'ailer. Si la liste de contrôle est conservée dans un référentiel de documentation, cela évite d'avoir à rechercher dans les e-mails le temps que l'ancien administrateur a envoyé un HOWTO.
À mon avis, une bonne liste de contrôle-documentation comprend également des sections sur les points de défaillance possibles et les réponses à ces défaillances. Cela peut rendre le document assez volumineux et déclencher des réponses TL; DR chez les collègues, donc je trouve que faire des modes de défaillance et de leurs réponses un lien à partir de la liste de contrôle plutôt que sur la page elle-même fait une liste de contrôle peu effrayante. Embrassez l'hypertextualité.
Document comme manuel
Le marché cible de ce type de documentation sont les personnes qui souhaitent en savoir plus sur le fonctionnement d'un système. La documentation sur le mode d'emploi doit pouvoir être dérivée de cette documentation, mais le plus souvent, je la vois comme un complément à la documentation de style liste de contrôle pour sauvegarder les décisions prises dans le flux de travail.
C'est la documentation où nous incluons des morceaux moelleux comme:
- Expliquant pourquoi il est configuré de cette façon.
- Cette section peut inclure des questions non techniques telles que la politique entourant la façon dont le tout a été acheté et installé.
- Expliquer les modes de défaillance courants et leurs réponses.
- Expliquer tout accord de niveau de service, écrit et de facto.
- De facto: "si cela échoue pendant la semaine des finales, c'est un problème de tout laisser tomber. Si pendant les vacances d'été, retournez vous coucher et faites-y face le matin."
- Définition des objectifs de mise à niveau et de refactoring.
- La politique peut être différente plus tard, pourquoi ne corrigeons-nous pas certaines des mauvaises idées introduites au début?
Qui sont tous très utiles pour obtenir une compréhension globale de l'ensemble du système. Vous n'avez pas besoin d'une compréhension globale pour exécuter de simples tâches d'automatisation humaine, vous en avez besoin pour comprendre pourquoi quelque chose a cassé comme il l'a fait et avoir une idée où le faire ne plus recommencer.
Vous avez également mentionné la documentation de récupération après sinistre qui doit être une liste de contrôle.
Je comprends, vous avez mes sympathies.
Oui, la documentation DR doit être aussi semblable à une liste de contrôle que possible.
Oui, la documentation DR est la plus résistante à la liste de contrôle en raison du nombre de façons dont les choses peuvent se briser.
Si votre liste de contrôle DR ressemble à:
- Appelez Dustin ou Karen.
- Expliquez le problème.
- Reculer.
Vous avez un problème. Ce n'est pas une liste de contrôle, c'est un aveu que la récupération de ce système est si complexe qu'il faut un architecte pour le comprendre. Parfois, c'est tout ce que vous pouvez faire, mais essayez de l'éviter si possible.
Idéalement, la documentation DR contient des listes de contrôle de procédure pour différentes choses:
- Procédures de triage pour déterminer ce qui n'a pas fonctionné, ce qui aidera à identifier ...
- Procédures de récupération pour certains cas de défaillance. Qui est soutenu par ...
- Scripts de récupération écrits bien à l'avance pour minimiser les erreurs humaines lors de la récupération.
- Documentation de style manuel sur les cas de défaillance, pourquoi ils se produisent et ce qu'ils signifient.
Les procédures de triage sont parfois toute la documentation DR que vous pouvez créer pour certains systèmes. Mais l'avoir signifie que l'appel à 4 heures du matin sera plus intelligible et l'ingénieur principal effectuant la récupération sera en mesure de résoudre le problème réel plus rapidement.
Certains cas d'échec ont des procédures de récupération simples. Documentez-les. En les documentant, vous pouvez trouver des cas où des listes de commandes sont entrées dans un ordre spécifique, ce qui est un excellent cas d'utilisation pour l'écriture de scripts; il peut transformer une procédure de récupération de 96 points en une procédure de 20 points. Vous ne saurez jamais si vous pouvez créer un script avant d'avoir mappé la procédure de récupération action par action.
La documentation de style manuel pour les cas de défaillance est le dernier filet de sécurité de fossé à utiliser en l'absence de procédures de récupération ou en cas d'échec des procédures de récupération. Il fournit les conseils Google nécessaires pour peut-être trouver quelqu'un d'autre qui a eu ce problème et ce qu'il a fait pour le résoudre.