Documentación como un manual vs. Documentación como una lista de verificación

He tenido conversaciones en el pasado con otras personas en mi departamento sobre documentación, específicamente, nivel de detalle y requisitos. En su opinión, la documentación es una simple lista de verificación de Y cosas que hacer cuando X cosas salen mal.

Estoy en desacuerdo. Creo que esto supone que todos los problemas en TI pueden resumirse fácilmente en simples listas de verificación de procedimientos de recuperación. Creo que ignora completamente la complejidad de la situación, y como las otras personas en el departamento no siempre tienen una comprensión profunda sobre el tema (es por eso que estoy escribiendo el documento, por lo que tienen algo a lo que referirse ) que la documentación debe incluir algunos antecedentes básicos, como:

• Propósito del (sub) sistema en cuestión
• Por qué está configurado de esa manera
• Expectativas de eventos que ocurrirán cuando se implementen las configuraciones / procedimientos
• Posibles problemas que pueden hacer que los procedimientos fallen

Sin embargo, estoy bastante votado sobre esto, por lo que es necesario reescribir mi documentación en un formulario que diga "Los pasos ABC aplicados en orden resolverán el problema X". A menudo escucho el lamento de que debe caber en una sola página de papel. Intente explicar la configuración de las ACL de Squid a alguien de esta manera, incluida la solución de problemas, a través de un documento de una sola página. Esa es solo una de la media docena de documentos que están "esperando ser escritos" como listas de verificación de recuperación.

¿Es realmente exagerado el método que estoy recomendando? ¿O tienen razón, y debería ocuparme de mis asuntos aquí y escribirles una simple lista de verificación? Mi preocupación es que, no importa qué tan bien escriba una lista de verificación de procedimientos, realmente no resuelve un problema que requiere un SysAdmin para pensar detenidamente. Si pasa tiempo haciendo una lista de verificación de los procedimientos de recuperación que termina sin resolver el problema (porque hay factores adicionales que no forman parte del documento, debido al enfoque limitado del documento ) y el propósito del el documento era para evitar volver a leer páginas de manual, wikis y sitios web nuevamente, entonces ¿por qué estoy revisando las mociones? ¿Me estoy preocupando demasiado o es un problema real?

EDITAR:

Actualmente no hay un puesto de servicio de asistencia en el departamento. La audiencia para la documentación sería para los otros administradores o para el jefe del departamento.

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

1. Llama a Dustin o Karen.
2. Explica el problema.
3. 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.

En realidad tampoco, utilizamos la documentación como un caso de prueba

Dicho esto, tenemos documentación escrita que acompaña a la documentación como manual . Teníamos listas de verificación en su lugar, pero al crecer descubrimos que eran propensas a errores y realmente fallaban en el sistema en su conjunto.

Sin embargo, tenemos una especie de "Lista de verificación de documentación" instalada, es decir, como se mencionó anteriormente, supervisamos ampliamente nuestros servicios. Hay un dicho:

Si no lo está monitoreando, no lo está administrando

Eso es totalmente cierto, pero otro debería ser:

Si no lo está monitoreando, no lo está documentando

Siempre que necesitemos migrar servicios, simplemente mantenemos abierto el "Grupo de servicio", "Grupo de host", lo que aplique (usamos Nagios, como se puede adivinar por el vocabulario) y no se migra siempre que haya un solo punto rojo en cualquiera de los servicios.

Las pruebas proporcionan una lista de verificación mucho mejor que cualquier lista de verificación escrita a mano. En realidad, es autodocumentado, tan pronto como tengamos alguna falla que no se monitoreó, la prueba al menos se agregará a Nagios, con eso obtenemos 2 Cosas gratis:

• sabemos cuando falla
• otro punto en la lista de verificación

La documentación "real" se guarda en un Wiki que menciona las probabilidades y los fines del servicio o prueba específica. Si falta, las personas lo agregarán tan pronto como necesitemos hacer alguna migración o necesitemos trabajar con él, hasta ahora ese enfoque ha funcionado muy bien.

Además, la documentación errónea se soluciona muy rápido, cada vez que algo falla, las personas comienzan a buscar la documentación e intentan resolver el problema con los HowTos allí, si está mal solo actualícelo con sus hallazgos.

Solo piense en los errores que uno podría crear siguiendo una lista de verificación y sin haber instalado ninguna prueba que le dé una casilla verde después de aplicarlos. No creo que sea posible separar la documentación del monitoreo.

Depende del público objetivo para su documentación.

Para los tipos de servicio de asistencia (nivel 1), una lista de verificación es el camino correcto; Por supuesto, esto supone que hay niveles más altos de apoyo con el conocimiento más profundo que usted describe.

Si la documentación es para el grupo de sistemas, siempre me equivoco al lado de más documentación. Ya es bastante difícil contar con la documentación adecuada para sobrevivir, si alguien (usted mismo) quiere escribir documentos más extensos con la información de fondo necesaria, ¡ninguna persona sensata debería interponerse en su camino!

Personalmente trato de mantener la documentación lo más simple posible. Tiende a incluir:

• Lo que se supone que debe hacer [X] (requisitos).
• Cómo se ha estructurado [X] a un alto nivel (diseño).
• Por qué implementé [X] como lo hice (consideraciones de implementación).
• Cómo la implementación de [X] no es estándar (soluciones alternativas).
• Problemas comunes con [X] y cómo resolverlos (problemas).

Entonces, es cierto que mi sección de problemas comunes es probable que sea una breve descripción de lo que sucedió y tutoriales de puntos sobre cómo solucionarlo.

Por lo general, supongo algún conocimiento del lector del sistema en cuestión (a menos que sea particularmente arcano). No tengo tiempo para hacer que la mayor parte de mi documentación técnica sea de nivel 1 o de gestión legible, pero un buen nivel 3 debería estar bien.

Creo que obviamente depende del tema. No todo se puede reducir a una simple lista de verificación, y no todo necesita un manual de usuario detallado.

Ciertamente parece que estás hablando de documentación interna, y en mi experiencia no puedes simplemente dar una lista de pasos, porque hay demasiadas opciones. Incluso crear una cuenta de usuario tiene algunas opciones (en nuestro entorno), por lo que nuestro documento "Nueva cuenta" enumera los pasos básicos en orden, pero para cada paso tiene una descripción de cuáles son las variaciones.

Por otro lado, nunca llegamos a escribir mucho de un documento para "Cómo parchar en una oficina", pero nuestro documento muy incompleto tampoco era una lista de verificación: mencionaba la convención que usamos para los colores de los cables, enfatizó que tenía que actualizar la hoja de cálculo que enumeraba las conexiones, y eso fue todo.

Entonces, ahora que he escrito esto, estoy totalmente de acuerdo: las listas de verificación paso a paso simplemente no serán suficientes para muchos procesos.

Estoy totalmente de acuerdo con usted en esto (a favor de la documentación exhaustiva) en parte porque estoy acostumbrado a tener predecesores que NO tenían mucho interés en los documentos. Como se ha dicho en publicaciones relacionadas, escribirlo no solo es bueno para los demás, sino que te ayuda a comprender mejor tu entorno y a solidificarlo en tu propia mente. Es un fin en sí mismo.

Como comentario aparte, encuentro que gran parte del rechazo proviene de una extraña creencia de que la documentación deficiente / inexistente = seguridad laboral. Ese tipo de pensamiento parece deshonesto y sombrío.

Felicitaciones a usted por romper el status quo.

Documento bastante, incluso tengo una lista de verificación de prioridad de documentos :-), sin embargo, no documentaré cosas que puedan considerarse conocimiento genérico (es decir, una buena descripción razonable del problema da una respuesta en la primera página de Google).

Para cualquier persona interesada aquí está mi lista de verificación de doc prio (funciona para mí, puede que no para usted, los comentarios y sugerencias son muy apreciados):

1. Cree un registro / diario personal en el que escriba todo lo que trabajó / conocimiento inteligente
2. Servicios, qué servicio es dónde, qué hace y para quién se hace (¿se debe crear algún acuerdo de SLA?)
3. Servidores, qué servidor es dónde, qué antigüedad y cuándo está escrito
4. Como arriba pero para equipos de red, UPS y similares
5. Como arriba pero para todas las máquinas de usuario
6. Diseño de la red física (qué cable va a dónde, cuánto dura y cuál es la calidad medida)
7. Descripción general de la configuración de software y licencias para servidores
8. Descripción general de la configuración de software y licencias para máquinas de usuario
9. Descripción general de la configuración de conmutadores, enrutadores y otro hardware dedicado
10. Contratos y SLA de todas las partes externas para las cuales mi servicio depende directamente (ISP, dominio, etc.)
11. Configure un sistema de tickets con wiki integrado para incluir todo lo anterior.
12. Para cada incidente, crea un ticket (incluso si solo lo usas para ti).
13. Cree un script que el domingo reúna tickets y los agrupe por tipo de problema.
14. El lunes, cree una solución automática o un documento de instrucciones para el usuario final para el problema más frecuente
15. Si el tiempo lo permite, haga el siguiente.
16. Si no hay nada más que hacer, busque un nuevo trabajo y dele a la persona que lo reemplaza el registro ;-)

Una lista de verificación está bien, siempre y cuando no pretenda estar completa documentación . Los últimos documentos que escribí vinieron en dos partes: XYZ para usuarios, que incluía bonitas capturas de pantalla sobre cómo usarlo; y XYZ para administradores de sistemas, que incluyó cómo se configuró y por qué (posiblemente incluso incluye el requisito comercial para que exista), trampas para evitar y una sección sobre solución de problemas. La solución de problemas es donde esperaría encontrar las listas de verificación. Quizás escribir las listas de verificación como XYZ for Tech Support podría ayudar a aclarar algo.

Ahora, leer entre líneas, enfocarse solo en las listas de verificación me indica una falta de pensamiento "Big Picture" y planificación a largo plazo que esperaría de alguien que: solo ha hecho soporte técnico; o un administrador junior recién comenzando; o está tan lleno de trabajo que no tienen tiempo para pensarlo; o nunca ha sido empujado a pensar en ello; o simplemente no le importa. No sé cuál de estos, si alguno, se aplica en su caso.

Soy bastante grande en la documentación. La compañía donde trabajo ahora siente que la documentación es importante, pero algunas personas en la compañía sienten que no tienen tiempo para escribirla. Esto puede dificultar la vida de cualquier persona además de la persona que lo hizo originalmente.

Para ciertas cosas, he escrito instrucciones paso a paso. Puede llamar a esto una lista de verificación si lo desea, pero en realidad no está destinado a ser marcado físicamente. Llamo a mi estilo de documentación los "pasos de jardín de infantes". Se basa en un libro de ejercicios MCSE que tuve para uno de los exámenes de Windows 2000. Los pasos son muy detallados, pero el uso de negrita / cursiva / tipo de letra hace que sea fácil pasar por alto y seleccionar las partes importantes para que no necesite leer todo después de haber aprendido los pasos.

Algunas cosas no se prestan bien a las instrucciones paso a paso, por lo que trato de proporcionar tantos datos de configuración como pueda. Alguna persona técnicamente inclinada que termine manteniendo el camino tendrá una mejor idea de a qué se enfrenta, y con suerte hará que su vida sea un poco más fácil cuando algo salga mal.