Documentación útil

sáb, 25 feb 2012 by Foron

La verdad, a estas alturas todavía no conozco a demasiada gente a la que le guste documentar. Es más, cuanto más técnico es uno, menos gusta.

Cada uno tendrá sus motivos, pero en mi caso, saber que nadie lee los documentos internos de instalaciones, actualizaciones, etc, que he escrito no me termina de hacer gracia.

Veamos el entorno en el que suelen moverse este tipo de documentos:

  • Son manuales que describen la instalación de servidores y aplicaciones, y que suelen guardarse en formato doc, pdf o similares en sistemas de gestión documental.
  • Su lógica es que un nuevo empleado pueda revisar el documento y que le sirva como referencia de la infraestructura.
  • Describen la instalación, paso a paso, de un servidor, por ejemplo de correo electrónico, las aplicaciones que ejecuta, ficheros de configuración, ....
  • Pretenden estar siempre actualizadas.

¿Cuál es el problema?

Según lo veo yo, y al igual que pasa con tantos otros "deberes" del trabajo (partes de actividad, gestión de procesos, ...), rompen completamente el flujo de trabajo del empleado: Para documentar, o para rellenar un parte de actividad, uno tiene que dejar lo que está haciendo, abrir libreoffice, buscar la plantilla, escribir texto, .... viene trabajo urgente, se aparca el documento, se retoma a los dos días, no se recuerda lo que se ha escrito, se repasa, ... otra vez trabajo prioritario, se vuelve a dejar el documento, ....

Y con las actualizaciones es todavía peor. No sé yo si mucha gente actualiza sus documentos cuando cambia algo de sus servidores (algo presumible en sistemas "vivos"), pero supone volver a dejar la rutina del trabajo, abrir el documento, buscar lo que hay que cambiar, redactar las modificaciones, repasar el documento, corregirlo, ....

Los wikis, que también se usan a menudo, tampoco están exentos de estos problemas: No siempre es fácil ir al navegador, buscar un documento que se escribió hace tiempo, modificarlo, ver referencias, mantenerlo al día, ....

Y para colmo, ¿Necesita esta documentación un nuevo empleado? Debemos suponer que alguien que va a trabajar con servidores de correo electrónico sabe como se instalan y lo que significa cada opción de configuración ¿Verdad?.

Con estos antecedentes, aquí van los mandamientos de forondarena.net para el trabajo de documentación:

  1. Por supuesto, hay que documentar todo aquello que no sea interno: Manuales para clientes y proveedores, documentos específicos para grupos de soporte y atención al cliente, ....
  2. Volviendo al trabajo interno de un departamento, sólo se documenta la definición del producto, quizá en forma de plan de proyecto, con su alcance, su público objetivo, lo que se pretende conseguir con él, .... En fin, estas cosas. Se pueden añadir detalles técnicos, pero más estructurales, de infraestructura, entorno tecnológico, ....
  3. Sólo hay una forma de garantizar que una instalación va a estar siempre bien documentada: Integrando la documentación en la rutina del trabajo. Dicho de otra forma, y concretando con un ejemplo, usando Puppet o similares en las instalaciones (y actualizaciones), y aprovechando su capacidad para auto-documentarse. Si alguien toca algo a mano, Puppet lo sobrescribe. Documentación actualizada, siempre.
  4. Si por algún motivo no se puede usar un sistema de gestión centralizada, al menos debe usarse software de control de versiones, ya sea git, subversion, cvs, o el que sea.
  5. La documentación más concreta, más detallada, de ficheros de configuración y scripts, como por ejemplo el motivo por el que se bloqueó una red en la configuración de apache, o la incidencia por la que se decidió aumentar el tamaño máximo de un mensaje en Postfix, deben estar al alcance del técnico, a ser posible sin tener que mover la vista de la terminal.

Y es este último punto el que me interesa en este post.

No, escribir comentarios en los mismos ficheros de configuración no es una opción, salvo para cosas puntuales. Además, una cosa es que queramos poder acceder rápido a la documentación, y otra que no podamos, en algún momento, pasarla a otros formatos, como html, con enlaces entre documentos, o pdf.

Entonces,.... Pues sí, sorpresa, ¡man!, el de toda la vida, y algunas aplicaciones construidas a su alrededor permiten hacer estas cosas, y mucho más.

Escribiendo páginas de manual

No, no voy a hablar sobre groff, ni mandoc, ni nada similar. Vamos a simplificar esto, aunque no haya nada complicado en groff, que conste. El objetivo es escribir documentación rápido, y no caer en los mismos errores que intentamos evitar.

A partir de ahora, sólo voy a escribir un pequeño resumen de este post del excelente blog dailyjs. Muy recomendable.

Por un lado, necesitamos un formato sencillo en el que escribir la documentación, y por otro, algún tipo de aplicación con la que convertir este texto en páginas compatibles con man, html, pdf, o lo que necesitemos.

Entre las opciones para el formato, la elección es markdown (que por cierto es interpretado por Github), y en cuanto a la aplicación que permite su conversión a otros formatos, tenemos varias alternativas, como ronn, o su versión para node.js ronnjs; pero en este post de ejemplo vamos a usar mantastic.herokuapp.com, que es una aplicación de Heroku que hace todo el trabajo por nosotros.

Pasemos a un ejemplo:

Tenemos un servidor de correo Postfix, con su correspondiente main.cf. Este fichero se sincroniza a través de Puppet, y se ha ido modificando en función de bugs, mejoras, incidencias de clientes y similares a lo largo de los meses.

En markdown, podríamos escribir algo como esto (que por cierto, se explica solo):

 main.cf(5) -- Configuración principal de Postfix
 ================================================

  ## SYNOPSIS

  `main.cf` - Fichero de configuración principal de Postfix.

  ## DESCRIPTION

  El fichero `main.cf` define gran parte de los cambios sobre la instalación base que se hacen a Postfix. Por lo tanto, cualquier cambio que se realice en este fichero debe ser probado en servidores de pre producción.


  `main.cf` es gestionado por `puppet(1)`. Los cambios que se apliquen directamente sobre este fichero serán sobreescritos.


  En la siguiente lista se encuentran las modificaciones más significativas que se han ido aplicando al fichero:

  * `message_size_limit`=20000:
       Se aplicó este límite de 20000 bytes a la configuración bla bla bla.

  * `dovecot_destination_recipient_limit`=1:
       Opción más segura para controlar las entregas locales bla bla bla. El transport dovecot se define en `master.cf(5)`

  * `smtpd_client_restrictions`=check_client_access cdb:/etc/postfix/clientes.out:
       Se define el fichero `clientes.out(5)`, como parte del grupo de restricciones en fase cliente, para rechazar aquellos clientes que no cumplan las normas de uso de la plataforma.

  ## INCIDENCIAS

  [1234](http://bugtrack.example.com/?id=1234) - Cliente x con problemas de envío.
  [5678](http://bugtrack.example.com/?id=5678) - Cliente z que envía miles de mensajes spam.

  ## HISTORY

  2012-02-20, Versión inicial.

  ## AUTHOR

  2012, Forondarena.net postmaster

  ## COPYRIGHT

  Forondarena.net

  ## SEE ALSO

  `puppet(1)`, `master.cf(5)`, `clientes.out(5)`

Si guardamos este fichero como "main.cf.5.md", y lo pasamos por la aplicación de Heroku, obtendremos una página de manual perfectamente formateada:

  curl -F page=@main.cf.5.md http://mantastic.herokuapp.com > main.cf.5

Si por el contrario optáis por usar una instalación local de ronn, o de ronnjs, se podría generar, además de lo anterior, una serie de páginas html enlazadas entre sí, tipo wiki, aunque para eso quizá habría que trabajar algo más el markdown.

Conclusión

Tal y como he venido diciendo, una buena documentación tiene tres niveles:

  1. Documentación general, de alto nivel, o externa. Puede ser un doc, pdf, etc.
  2. Documentación sobre instalaciones de máquinas, actualizaciones de software, etc. Muy dinámica y difícil de mantener si no se integra completamente en el día a día del trabajo. Los sistemas de configuración centralizados son la clave.
  3. Documentación detallada sobre scripts y ficheros concretos. No conozco muchos entornos en los que se tengan realmente bien documentados todos los scripts y ficheros de configuración. Algunos son capaces de incluir comentarios inline, pero esto no siempre es suficiente, y se corre el riesgo de terminar con ficheros de configuración demasiado "densos". Sólo pueden documentarse correctamente a través de aplicaciones muy sencillas y directas.

Notas

El fichero en markdown y su correspondiente página de manual están disponibles en Github.

Una vez más, el impulso definitivo para publicar esto se debe al post de dailyjs que he referenciado anteriormente.

Dejo como ejercicio el uso de ronn o ronnjs en línea de comandos, la generación de páginas html, la gestión centralizada, o incluso montar un servidor de páginas de manual (pista: tcpserver/tcpclient, netcat, socat, ...).


Comments