Documentation en tant que manuel ou documentation en tant que liste de contrôle

J'ai eu des discussions dans le passé avec d'autres personnes de mon service au sujet de la documentation, en particulier du niveau de détail et des exigences. À leur avis, la documentation est une simple liste de contrôle de Y choses à faire lorsque X choses tournent mal.

Je ne suis pas d'accord. Je pense que cela suppose que tous les problèmes informatiques peuvent être facilement résumés en de simples listes de contrôle des procédures de récupération. Je pense que cela ignore complètement la complexité de la situation, et comme les autres employés du ministère n'ont pas toujours une compréhension approfondie de la question (c'est pourquoi j'écris le document - ils ont donc quelque chose à se référer ) que la documentation devrait comprendre des informations de base, telles que:

• Objet du (sous) système en question
• Pourquoi est-il configuré de cette manière
• Attentes d'événements se produisant lorsque les paramètres / procédures sont mis en œuvre
• Problèmes potentiels pouvant entraîner l'échec des procédures

Cependant, je suis plutôt mis à l'écart à ce sujet, donc ma documentation doit être réécrite dans un formulaire qui dit "Les étapes ABC appliquées pour résoudre le problème X". J'entends souvent la complainte qu'il doit tenir sur une seule page de papier. Essayez d'expliquer la configuration des listes de contrôle d'accès Squid à quelqu'un de cette manière, y compris le dépannage, via un document d'une seule page. Ce n'est que l'un d'une demi-douzaine de documents qui "attendent d'être écrits" en tant que listes de contrôle de récupération.

La méthode que je préconise va-t-elle vraiment par-dessus bord? Ou ont-ils raison, et je devrais simplement m'occuper de mes affaires ici et leur écrire une simple liste de contrôle? Ma préoccupation est que, peu importe la façon dont vous écrivez une liste de contrôle de procédure, cela ne résout vraiment pas un problème qui nécessite un SysAdmin pour réfléchir. Si vous passez du temps à faire une liste de contrôle des procédures de récupération qui finit par ne pas résoudre le problème (car il existe des facteurs supplémentaires qui ne font pas partie du document, en raison de la focalisation étroite du document ), et le but de la Le document visait à éviter de relire les pages de manuel, les wikis et les sites Web, alors pourquoi suis-je en train de passer en revue les motions? Suis-je juste trop inquiet, ou est-ce un vrai problème?

ÉDITER:

Il n'y a actuellement aucun poste de service d'assistance dans le département. Le public de la documentation serait pour les autres administrateurs ou pour le chef de département.

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 à:

1. Appelez Dustin ou Karen.
2. Expliquez le problème.
3. 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.

En fait, ni l'un ni l'autre, nous utilisons la documentation comme test

Cela étant dit, nous avons une documentation écrite qui accompagne la documentation en tant que manuel . Nous avions des listes de contrôle en place, mais en grandissant, nous avons constaté qu'elles étaient sujettes aux erreurs et échouaient vraiment sur le système dans son ensemble.

Nous avons cependant installé une sorte de "documentation en tant que liste de contrôle", c'est-à-dire - comme mentionné ci-dessus - que nous surveillons de manière approfondie nos services. Il y a un dicton:

Si vous ne le surveillez pas, vous ne le gérez pas

C'est tellement vrai, mais un autre devrait être:

Si vous ne le surveillez pas, vous ne le documentez pas

Chaque fois que nous devons migrer des services, nous gardons simplement le "Service Group", "Host Group", tout ce qui s'applique (nous utilisons Nagios, comme vous pouvez le deviner d'après le vocabulaire) ouvert et il n'est pas migré tant qu'il n'y a qu'un seul point rouge sur l'un des services.

Les tests fournissent une liste de contrôle bien meilleure que n'importe quelle liste de contrôle manuscrite pourrait fournir. Il s'agit en fait d'une auto-documentation, dès que nous avons un échec qui n'a pas été surveillé, le test sera au moins ajouté à Nagios, avec lequel nous obtenons 2 choses gratuitement:

• on sait quand ça échoue
• un autre point sur la liste de contrôle

La "vraie" documentation est conservée dans un Wiki mentionnant les cotes et les fins du service ou du test spécifique. S'il manque, les gens l'ajouteront dès que nous aurons besoin de migrer ou de travailler avec, jusqu'à présent, cette approche a très bien fonctionné.

De plus, la documentation erronée est résolue très rapidement, chaque fois que quelque chose échoue, les gens commencent à rechercher la documentation et essaient de résoudre le problème avec les HowTos qui s'y trouvent, si c'est faux, mettez-le à jour avec vos résultats.

Pensez simplement aux erreurs que l'on pourrait éventuellement créer en suivant une liste de contrôle et en n'ayant installé aucun test qui vous donnera une case verte après les avoir appliquées. Je ne pense pas qu'il soit possible de séparer la documentation de la surveillance.

Cela dépend du public cible de votre documentation.

Pour les types de helpdesk (niveau 1), une liste de contrôle est la bonne façon de procéder; bien sûr, cela suppose qu'il existe des niveaux de soutien plus élevés avec les connaissances plus approfondies que vous décrivez.

Si la documentation est pour le groupe des systèmes, je me trompe toujours du côté de plus de documentation. Il est déjà assez difficile d'avoir une documentation adéquate juste pour s'en sortir, si quelqu'un (vous-même) veut écrire des documents plus complets avec les informations de base requises - aucune personne sensée ne devrait vous gêner!

Personnellement, j'essaie de garder la documentation aussi simple que possible. Il comprend généralement:

• Ce que [X] est censé faire (exigences).
• Comment [X] a été structuré à un niveau élevé (conception).
• Pourquoi j'ai implémenté [X] comme je l'ai fait (considérations d'implémentation).
• Comment l'implémentation de [X] n'est pas standard (solutions de contournement).
• Problèmes courants avec [X] et comment les résoudre (problèmes).

Donc, certes, ma section sur les problèmes courants est susceptible d'être une brève description de ce qui s'est passé et des procédures pas à pas sur la façon de résoudre ce problème.

J'assume habituellement certaines connaissances du lecteur du système en question (à moins qu'il ne soit particulièrement arcanique). Je n'ai pas le temps de rendre la plupart de ma documentation technique de niveau 1 ou de gestion lisible - mais un indice de niveau 3 devrait convenir.

Je pense que cela dépend évidemment du sujet. Tout ne peut pas être réduit à une simple liste de contrôle, et tout n'a pas besoin d'un manuel d'utilisation détaillé.

On dirait certainement que vous parlez de documentation interne, et d'après mon expérience, vous ne pouvez pas simplement donner une liste d'étapes, car il y a trop de choix. Même la création d'un compte utilisateur a quelques options (dans notre environnement) donc notre document "Nouveau compte" répertorie les étapes de base dans l'ordre, mais pour chaque étape a une description de ce que sont les variations.

D'un autre côté, nous n'avons jamais réussi à écrire une grande partie d'un document pour "Comment patcher dans un bureau", mais notre document très sommaire n'était pas non plus une liste de contrôle - il mentionnait la convention que nous avons utilisée pour les couleurs des câbles, a souligné que vous deviez mettre à jour la feuille de calcul qui a énuméré les connexions, et qui était à ce sujet.

Donc, maintenant que j'ai écrit cela, je suis totalement d'accord: les listes de contrôle étape par étape ne suffiront pas pour de nombreux processus.

Je suis fortement d'accord avec vous à ce sujet (en faveur d'une documentation exhaustive) en partie parce que j'ai l'habitude d'avoir des prédécesseurs qui ne s'intéressaient PAS du tout aux documents. Comme cela a été dit dans des articles connexes, l'écrire n'est pas seulement bon pour les autres, mais vous aide à mieux comprendre votre environnement et à le solidifier dans votre propre esprit. C'est une fin en soi.

Soit dit en passant, je trouve qu'une grande partie du refoulement vient d'une croyance étrange que la documentation merdique / inexistante = la sécurité d'emploi. Ce genre de pensée semble juste malhonnête et obscur.

Bravo à vous d'avoir contourné le statu quo.

Je documente beaucoup, j'ai même une liste de contrôle de priorité des documents :-), mais je ne documenterai pas des choses qui peuvent être considérées comme des connaissances génériques (c'est-à-dire qu'une bonne description raisonnable du problème donne une réponse dans la première page de Google).

Pour toute personne intéressée, voici ma liste de contrôle doc prio (fonctionne pour moi, peut-être pas pour vous, les commentaires et suggestions sont très appréciés):

1. Créez un journal / journal personnel où vous notez tout ce que vous avez fait
2. Services, quel service est où, que fait-il et pour qui est-il fait (tout accord SLA? Faut-il en créer un?)
3. Serveurs, quel serveur est où, quel âge et quand est-il écrit
4. Comme ci-dessus, mais pour les équipements réseau, UPS et similaires
5. Comme ci-dessus mais pour toutes les machines utilisateur
6. Disposition du réseau physique (quel câble va où, combien de temps est-il et quelle est la qualité mesurée)
7. Présentation de la configuration des logiciels et des licences pour les serveurs
8. Présentation de la configuration des logiciels et des licences pour les machines utilisateur
9. Présentation de la configuration des commutateurs, routeurs et autres matériels dédiés
10. Contrats et SLA de toutes les parties externes pour lesquelles mon service dépend directement (FAI, domaine, etc.)
11. Mettre en place un système de ticket avec wiki intégré pour y mettre toutes les choses ci-dessus.
12. Pour chaque incident, créez un ticket (même si vous ne l'utilisez que pour vous-même).
13. Créez un script qui rassemble les tickets le dimanche et les regroupe par type de problème.
14. Lundi, créez une solution automatique ou un document de l'utilisateur final pour le problème le plus fréquent
15. Si le temps le permet, faites la suivante.
16. Si vous n'avez plus rien à faire, cherchez un nouvel emploi et remettez le journal à la personne qui vous remplace ;-)

Une liste de contrôle est très bien, tant qu'elle ne prétend pas être une documentation complète . Les derniers documents que j'ai écrits se sont divisés en deux parties: XYZ for Users, qui comprenait de jolies captures d'écran sur la façon de l'utiliser; et XYZ pour les administrateurs système, qui comprenait comment il a été configuré et pourquoi (y compris éventuellement l'exigence commerciale pour qu'il existe), les pièges à éviter et une section sur le dépannage. Le dépannage est l'endroit où je m'attends à trouver les listes de contrôle. Peut-être que l'écriture des listes de contrôle en tant que XYZ pour le support technique pourrait aider à faire valoir un point.

Maintenant, la lecture entre les lignes, en se concentrant uniquement sur les listes de contrôle, m'indique un manque de réflexion et de planification à long terme que j'attendrais de quelqu'un qui: n'a fait que du support technique; ou un administrateur junior débutant; ou est tellement submergé de travail qu'ils n'ont pas le temps d'y penser; ou n'a jamais été poussé à y penser; ou tout simplement s'en fiche. Je ne sais pas lequel, le cas échéant, s'applique à votre cas.

Je suis assez gros sur la documentation. L'entreprise dans laquelle je travaille à présent estime que la documentation est importante, mais certaines personnes de l'entreprise estiment qu'elles n'ont pas le temps d'écrire de la documentation. Cela peut rendre la vie difficile à quiconque en dehors de la personne qui l'a fait à l'origine.

Pour certaines choses, j'ai écrit des instructions étape par étape. Vous pouvez appeler cela une liste de contrôle si vous le souhaitez, mais elle n'est pas vraiment destinée à être physiquement cochée. J'appelle mon style de documentation les «étapes de la maternelle». Il est calqué sur un cahier d'exercices MCSE que j'ai eu pour l'un des examens Windows 2000. Les étapes sont très détaillées, mais l'utilisation de caractères gras / italiques / permet de passer facilement en revue et de sélectionner les parties importantes de sorte que vous n'avez pas besoin de tout lire après avoir appris les étapes.

Certaines choses ne se prêtent pas bien aux instructions étape par étape, j'essaie donc de fournir autant de données de configuration que possible. Une personne techniquement encline qui finit par continuer sur la route aura une meilleure idée de ce à quoi elle fait face et, espérons-le, cela facilitera un peu la vie en cas de problème.