Documentar un entorno de laboratorio

Documentar un entorno de laboratorio

Se me asignó la tarea de configurar y administrar un entorno de laboratorio completamente nuevo, que consta de muchas máquinas con diferentes funciones. Hay un host de VM, varios servidores web, varios servidores de bases de datos y demás.

Hay necesidades y procesos muy específicos que deben documentarse como parte de este entorno de laboratorio; por ejemplo, no queremos que se activen las actualizaciones automáticas de Windows y hay muchas ideas que queremos capturar para explicarlas a varias partes diferentes ( ejecutivos, gerentes, desarrolladores, gerentes de TI, gente de control de calidad).

Mientras hago la configuración, realmente quiero capturar estas conversaciones en algún tipo de documento formal. Iba a seguir adelante y crear un .doc de Word, organizando cada función del servidor con varias secciones discretas:

  • Resumen ejecutivo
  • Necesidades de mantenimiento
  • Inventario de software instalado
  • Hardware disponible
  • Valores predeterminados de hardware

Lo que me gustaría saber es si existen mejores plantillas que pueda seguir al crear documentación para estas máquinas. Espero que todo lo que termine creando sea lo suficientemente bueno para que alguien más reconstruya las máquinas si es necesario.

Respuesta1

Los aspectos más importantes para un buen sistema de documentación son:

  • Fácil de actualizar (o la gente no lo actualiza, haciéndolo peor que inútil)
  • Fácil acceso: desde cualquier ubicación, desde múltiples dispositivos.
  • Bien organizado: fácil para las personas encontrar la información que necesitan y mínima duplicación de la misma información.

Probé documentos de Word. Fallan en los 3 puntos. Los documentos de Word son difíciles de actualizar, terminas con personas que tienen copias diferentes, etc.

El mejor sistema que he encontrado para mi uso es un wiki. DokuWiki funciona bastante bien para mis propósitos. Puedo acceder y actualizarlo fácilmente desde cualquier lugar.

Tengo mi wiki con páginas que describen toda la configuración de la red, que enlazan con páginas para cada servidor, clúster y aplicación. De esta manera, todos los detalles sobre un elemento en particular se guardan en páginas separadas y se pueden vincular desde cualquier lugar que sea relevante; cuando algo cambia, solo tengo que cambiarlo en una página y puedo encontrar fácilmente la información que estoy buscando. para.

También le permite especificar plantillas de espacio de nombres, de modo que cuando creo una nueva página de servidor, se completa previamente con tablas para ingresar direcciones IP, configuración de hardware, etc. Todos los campos vacíos tienen escrito FIXME, por lo que puedo buscar en toda la wiki. para FIXME y vea lo que falta en la documentación.

Si realmente quieres ser sofisticado, puedes escribir complementos que tomen elementos como archivos de configuración, los analicen y los muestren en un formato fácil de leer. Por ejemplo, escribí un complemento llamado PatchPanel que toma una descripción de texto de un panel de conexiones de red y lo dibuja con etiquetas para indicar dónde va cada puerto.

http://blog.emsley.ca/2014/04/documentation.htmltiene una descripción más completa de cómo lo configuré (descargo de responsabilidad: enlace a mi blog, aunque completamente sobre el tema).

información relacionada