Cuando escribo el mío siempre me he dedicado a escribir dos tres juegos. La lista de verificación para terminar, con un apéndice MUCHO MÁS LARGO sobre la arquitectura del sistema, que incluye por qué las cosas se hacen de la manera en que están, los puntos de conflicto probables cuando se conecta y los supuestos de diseño abstracto. seguido de una lista de problemas probables y sus soluciones, seguida de una sección más larga con información sobre cómo funciona un sistema, por qué lo hace de esa manera y otra información útil para orientar a las personas en la dirección correcta en caso de que ocurra algo único.
En mi último trabajo se nos pidió que escribiéramos un documento para que incluso las personas del servicio de asistencia de nivel 1 pudieran volver a plantear las cosas. Esto requirió listas de verificación, que generalmente quedaron desactualizadas dentro de los 3 meses posteriores a la escritura. Se nos recomendó encarecidamente que escribiéramos guías de solución de problemas siempre que sea posible, pero cuando el árbol de contingencia tiene más de tres ramas, simplemente no puede escribir ese documento sin ir abstracto.
Cuando dejando mi último trabajo, di vuelta en una página 100 de 'cómo hacer mi trabajo' manual antes de irme. Tenía lo abstracto, filosofía de diseño y puntos de integración. Como presumiblemente estaba escribiendo para otro administrador de sistemas que me iba a reemplazar, apunté a alguien que podía tomar nociones abstractas y convertirlas en acciones concretas.
Han pasado cinco años y creo que mi opinión sobre esto ha cambiado un poco. Tanto el Documento como Manual y el Documento como Lista de Verificación tienen lugares muy valiosos en la jerarquía de documentación y ambos necesitan ser producidos. Sin embargo, se dirigen a audiencias muy diferentes.
Documento como lista de verificación
El mercado objetivo para este tipo de documentación son los compañeros de trabajo que quieren saber cómo hacer algo. Vienen en dos tipos:
- Compañeros de trabajo que solo quieren saber cómo hacer algo y no tienen tiempo para hojear un manual de quince páginas y descubrir los pasos por sí mismos.
- Procedimientos que son bastante complejos en pasos, pero solo necesitan ejecutarse de vez en cuando.
La impaciencia es el conductor para el primer tipo. Tal vez su compañero de trabajo en realidad no quiera saber por qué la salida debe canalizarse a través de una expresión regular perl de 90 caracteres, solo que tiene que ser así para cerrar el ticket. Definitivamente incluya una declaración como "Para obtener una explicación detallada de por qué este flujo de trabajo tiene este aspecto, siga este enlace" en la lista de verificación para aquellos que quieran saber por qué.
El segundo punto es para procedimientos que no se ejecutan con frecuencia pero que contienen dificultades. La lista de verificación actúa como un mapa para evitar el Certain Doom de simplemente volarlo. Si la lista de verificación se mantiene en un repositorio de documentación, se ahorra tener que buscar el correo electrónico por el tiempo que el administrador anterior envió un CÓMO.
En mi opinión, la buena documentación de la lista de verificación también incluye secciones sobre posibles puntos de falla y respuestas a esas fallas. Esto puede hacer que el documento sea bastante grande y desencadenar respuestas TL; DR en los compañeros de trabajo, por lo que creo que hacer que los modos de falla y sus respuestas sean un enlace de la lista de verificación en lugar de en la página en sí misma crea una lista de verificación sin miedo. Abraza la hipertextualidad.
Documento como manual
El mercado objetivo para este tipo de documentación son las personas que desean aprender más sobre cómo funciona un sistema. La documentación de estilo de cómo hacer una cosa debería poder derivarse de esta documentación, pero más comúnmente lo veo como un suplemento a la documentación de estilo de lista de verificación para respaldar las decisiones tomadas en el flujo de trabajo.
Esta es la documentación donde incluimos piezas masticables como:
- Explicando por qué está configurado de esta manera.
- Esta sección puede incluir cuestiones no técnicas como las políticas que rodean cómo se compró e instaló todo.
- Explicando los modos de falla comunes y sus respuestas.
- Explicar cualquier acuerdo de nivel de servicio, tanto escrito como de facto.
- De facto: "si esto falla durante la semana final, es un problema para todo. Si durante las vacaciones de verano, vuelve a dormir y lidia con eso por la mañana".
- Establecer objetivos de actualización y refactorización.
- La política puede ser diferente más tarde, ¿por qué no arreglamos algunas de las malas ideas que introdujimos al principio?
Todos los cuales son muy útiles para obtener una comprensión integral de todo el sistema. No necesita una comprensión integral para ejecutar tareas simples de automatización humana, lo necesita para descubrir por qué algo se rompió de la manera en que lo hizo y tener una idea de dónde hacerlo para que no vuelva a hacerlo.
También mencionó la documentación de Recuperación ante desastres que tiene que ser una lista de verificación.
Entiendo, tienes mis simpatías.
Sí, la documentación de DR debe ser lo más parecida a una lista de verificación posible.
Sí, la documentación de DR es la más resistente a las listas de verificación debido a la cantidad de formas en que las cosas pueden romperse.
Si su lista de verificación DR se ve así:
- Llama a Dustin o Karen.
- Explica el problema.
- Un paso atrás.
Tienes un problema. Esa no es una lista de verificación, es una admisión de que la recuperación de este sistema es tan compleja que necesita un arquitecto para darse cuenta. A veces eso es todo lo que puedes hacer, pero trata de evitarlo si es posible.
Idealmente, la documentación de DR contiene listas de verificación de procedimientos para algunas cosas diferentes:
- Procedimientos de selección para descubrir qué salió mal, lo que ayudará a identificar ...
- Procedimientos de recuperación para ciertos casos de falla. Que es apoyado por ...
- Scripts de recuperación bien escritos de antemano para ayudar a minimizar los errores humanos durante la recuperación.
- Documentación de estilo manual sobre los casos de falla, por qué ocurren y qué significan.
Los procedimientos de triaje son a veces toda la documentación de DR que puede hacer para algunos sistemas. Pero tenerlo significa que la llamada a las 4:00 a.m. será más inteligible y el ingeniero superior que realiza la recuperación podrá resolver el problema real más rápido.
Algunos casos de falla tienen procedimientos de recuperación directos. Documentarlos. Al documentarlos, puede encontrar casos en los que se ingresan listas de comandos en un orden específico, lo cual es un gran caso de uso para las secuencias de comandos; puede convertir un procedimiento de recuperación de 96 puntos en uno de 20 puntos. Nunca sabrá si puede escribir algo hasta que asigne el procedimiento de recuperación acción por acción.
La documentación de estilo manual para casos de falla es el último sistema antirretorno utilizado cuando NO hay procedimientos de recuperación o los procedimientos de recuperación fallaron. Proporciona las sugerencias de google necesarias para encontrar a alguien que haya tenido ese problema y lo que hicieron para solucionarlo.