Comenzando con la documentación

No hemos estado haciendo ninguna documentación en mi lugar de trabajo. Soy completamente nuevo en esto y solicito orientación para comenzar.

Tengo algunas preguntas:

• ¿Cuáles son los documentos esenciales que un administrador de sistemas debe escribir y mantener? ¿Y por qué son tan importantes?

• ¿Cómo mantiene su documentación sincronizada con el sistema? ¿Cómo minimizas la duplicación de información?

• ¿Guías recomendadas, mejores prácticas, antipatrones?

desde 2003 estoy documentando todo en nuestra wiki interna.

Servidores

• especificaciones de hardware
• información de garantía
• información de red
• y, por supuesto, software y configuración instalados

Flujos de trabajo

por ejemplo, cómo agregar o eliminar un usuario y darle acceso a todos los servicios relevantes

Links importantes

• enlace a todas sus interfaces web
• enlace a las URL de monitoreo (nagios, munin, apc-tracking ...)
• enlace a la wiki (¡para la versión impresa!)

Instrucciones de emergencia

qué hacer si el servidor de intranet / internet / servidor web / etc. están inactivos

Importante:

¡Elija un motor wiki con fácil exportación a PDF!
No es útil si está de vacaciones, el servidor que ejecuta su wiki está inactivo y nadie sabe qué hacer porque su documentación está fuera de línea

Echa un vistazo a twiki, docuwiki o mediawiki.

Por cierto:

hay un complemento de OpenOffice.org para escribir directamente en mediawiki, muy conveniente.

EDITAR:

También es bueno escribir algunas informaciones /home/adminuser/maintenance. Esto se hace rápido y puede ser muy útil si varios administradores trabajan en un servidor. p.ej:

2009-06-27 -thorsten-
          running aptitude update && aptitude full-upgrade
          everything seems ok
2009-06-25 -andreas-
          cups-pdf wasn't reachable. restarted cups
2009-06-23 -thorsten-
          deleted old log under /var/log/squid
etc.

Si bien se da cuenta de que, aunque todos quieren (y necesitan) documentación, también debe reconocer que nadie tiene tiempo para leer y estudiar las cosas.

Por lo tanto, no escriba documentación que deba estudiarse; en su lugar, estructure su documentación de manera que le permita a alguien encontrar rápidamente la información que necesita, cuando la necesita, lo cual puede ocurrir mientras el sistema está inactivo y el CTO está inactivo. respirando por su cuello.

Con esto en mente, algunas sugerencias ...

• Evite grandes bloques de texto.
• Las listas de viñetas son tu amigo
• Un diagrama claro es dorado.
• La repetición es una buena idea (1)
• Facilite la actualización y extensión

(1) No cree una fuente de verdad y obligue a las personas a cazarla. Cuanto más importante es la idea, más debes repetirla.

Documentos esenciales:

• Documentación del servidor: especificaciones / diseños de disco / software instalado / cualquier cosa importante
• Procedimientos comunes: todo lo que se haga que no sea 'trivial' debe tener un procedimiento documentado, especialmente si es algo que no se ha hecho antes.

Mantener la documentación sincronizada puede ser básicamente un asunto de 'arreglarlo cuando vea errores'. Junto con esto, debe darse cuenta de que la documentación puede y estará desactualizada, y que no debe seguirse a ciegas sin tener esto en cuenta. La documentación está ahí para ayudar a un administrador en las tareas, no para ser un conjunto de reglas paso a paso que reemplacen el pensamiento crítico.

Minimizar la duplicación: usar algo como wikis donde puede vincular la documentación puede ayudar con esto, en lugar de repetir la información, solo tiene que vincularla. El problema es que la persona que escribe la documentación necesita saber que la información que está a punto de duplicar ya existe. Esta suele ser una cuestión de buena organización.

Descubrí que crear una plantilla es de gran ayuda. En mi caso, es una plantilla de Word, pero use las suites que desee. Cree un archivo esqueleto, completo con el campo de tabla de contenido y las secciones que desee. Una vez que lo haya usado un par de veces y haya realizado ajustes de ajuste, creará nuevos documentos mucho más rápido. La consistencia del formato será de gran ayuda, tanto para la creación de documentos como para su uso posterior. La documentación debe almacenarse en un lugar lógico y en una estructura de directorio lógico.

Personalmente me opongo a la repetición por el simple hecho de que hace que el mantenimiento sea innecesariamente difícil y lento. En lugar de duplicar documentos o partes de documentos, cree referencias a otros documentos cuando corresponda. Si algo cambia, nunca debería tener que cambiar la documentación relevante más de una vez o en más de un lugar, de lo contrario, tendrá una colección de documentos en conflicto, lo que no ayuda a nadie.

Mientras crea su documentación, solo tenga en cuenta para qué sirve. Alguien más tarde tendrá que usarlo. ¿Será utilizable para hacer el trabajo sin conocimiento previo?

No es una respuesta directa a su pregunta, sino un puntero en la dirección correcta:

Encontré La práctica de la administración de sistemas y redes , de Limoncelli y Hogan (también conocida como la Biblia Sysadmin), que es bastante valiosa porque se trata de cuestiones de "mejores prácticas", como la documentación. Si aún no lo sabe, asegúrese de investigarlo cada vez que tenga la oportunidad.

Para mí, la consideración más importante es que sea fácil de usar. Si es difícil de orquestar, la gente lo evitará. Elijo el wiki de Trac como medio para nuestra documentación por estos motivos:

• Céntrico.

  Más de una copia activa de cualquier documento lleva a confusión. Si puede referir a todos al mismo lugar, contribuyentes y público, entonces puede simplificar el proceso.

• Edición y formateo simples.

  Se desperdicia mucho tiempo en bonitas plantillas de Word y se ajusta al estilo del último autor. Si no molesta a la gente con esto, entonces es más fácil editar sobre la marcha y los contribuyentes están más inclinados a hacerlo. Separe los elementos tanto como desee con TracLinks.

• Historial de auditoria.

  Es importante saber quién hizo qué cambio, cuándo y por qué. Si puede vincularlo con tickets de solicitud de cambio y registros de confirmación de configuración, aún mejor. Los ganchos SVN commit son excelentes para esto.