¿Cómo evita que la documentación del servidor no esté sincronizada con la configuración real?

Tenemos una documentación razonablemente buena para nuestro entorno (en formato AsciiDoc) que recientemente permitió a otra persona recrear toda la configuración desde cero en menos de 30 minutos.
Sin embargo, noté que después de la configuración inicial, sucede fácilmente que se realizan pequeños cambios en el sistema (por ejemplo: inetd se deshabilita, mi servidor IMAP escucha en un puerto adicional para conexiones ManageSieve, se agrega un nuevo enrutador a la configuración exim) No termine en la documentación de inmediato (si es que lo hace).

Mi idea era evitar este problema (parcialmente?) Generar la documentación de los archivos de configuración y los comentarios su interior - una forma de implementar esto puede ser para poner /etcy /usr/local/etcen algún sistema de gestión de código fuente (digamos - GIT) y luego ejecutar una script que regenera la documentación en cada confirmación. Sin embargo, no estoy seguro de si eso sería excesivo y / o demasiado difícil de corregir (después de todo, no quiero copias completas de los archivos de origen en mi documentación, sino solo las diferencias).

¿Cómo evitan otras personas que la documentación del servidor se desactualice? ¿Existe una buena manera de mantenerlos sincronizados automáticamente o simplemente tiene la disciplina de actualizar la documentación al mismo tiempo que modifica el sistema?

Nunca se alejará de cierta documentación, pero como lo insinuó, hay sistemas que pueden integrarse en su proceso de cambio para cubrir gran parte de ella.

• Use una herramienta de administración de configuración (como títeres o chef ).
• Almacene su configuración de una manera controlada por cambio. (como git o SVN )
• Asegúrese de que los humanos puedan leer / acceder la configuración (es decir, texto sin formato, base de datos de búsqueda)

De esta manera, la documentación de nivel inferior que todos normalmente echamos de menos (o no nos molestamos) se aplica almacenando esa información de despliegue en elementos de configuración o código como parte del sistema al que realiza los cambios. Esto también tiene una ventaja adicional de que el proceso se volverá más repetible en el futuro.

Todavía es necesario actualizar la documentación externa, pero se vuelve de muy alto nivel con punteros para "desplegar x" o "desplegar y" en lugar de largas listas de comandos / archivos. Esto además hace que los cambios de documentación sean menos frecuentes y fáciles, lo que también significa que será más probable que se realice.

Además, antes de irse a casa a preparar cerveza, con títeres alguien probablemente ya ha escrito algo para administrar lo que quiere.

Si solo administra uno o dos sistemas pequeños, configurar un sistema de administración de configuración grande como puppet o chef parece una exageración. (Sin embargo, si planea tener más sistemas en el futuro, ¡hágalo ahora!)

Para una configuración pequeña como esta, recomendaría usar algo como etckeeper, un programa que se coloca /etcen un gitrepositorio y proporciona algunas funciones útiles, como realizar una confirmación automática cada vez que instala, actualiza o elimina un paquete.

Solo tiene que actualizar su documentación cada vez que realice un cambio en el sistema. También conocido como Change Management.

El hecho de que la mayoría de las empresas implementen la gestión del cambio de una manera tan ridícula como para empeorar las cosas no debería menoscabar la utilidad del concepto básico ni evitar que lo haga bien.

Solía ​​usar htmlo algún tipo de wiki para rastrear todas mis configuraciones. Ahora trabajo en una tienda de Windows con ( estremecimiento ) SharePoint, así que ahora uso las "plantillas" de documentos de Word que creé para rastrear cada sistema que tengo y cada cambio de configuración que hago, lo cual no es tan malo como parece, dado que muchos Los sistemas son solo copias de otros que pueden ser agrupados en el mismo documento. (Y guardo copias locales de todos mis documentos en mi disco duro, en realidad organizado de manera sensata, además de arrojarlos al montón desorganizado que es el sitio de SharePoint de cualquier persona).

El mayor desafío es realmente hacer el tiempo para documentar, lo cual hago agregando el tiempo de documentación como parte del tiempo para realizar el cambio. Entonces, no es tan difícil, especialmente si eres un poco idiota y no te importa decirle a la gente que se joda y espere en la cola porque estás demasiado ocupado para su problema en este momento.