¿Cuál es el formato adecuado para documentar?

"Uno de los grandes dilemas al momento de hacer la documentación es el formato en el cuál se debería realizar"

Decidir el formato adecuado a la hora de crear documentación no es una tarea facil. En ocasiones utilizar un simple editor de textos es la elección más rápida, aunque no necesariamente la mejor. Contar con un formato, por así decirlo neutral y que a través de alguna herramienta o comando pueda generar un archivo en formato html o pdf sería una buena opción y más si sabemos que la documentación que generemos se colocara en línea a través de la página de la empresa.

¿Qué es Docbook?

Básicamente Docbook es un conjunto de etiquetas xml que junto con otros archivos xsl y otros recursos son procesados por un parser (convertidor o interprete de xml) y transformados en archivos PDF o HTML single o multipage.

La ventaja de crear documentación técnica en este formato es que el escritor debe olvidarse de la vista de documento (aunque no del todo) y poder poner mayor atención en el contenido. Si bien el conjunto de etiquetas que componen Docbook es bastante amplio y su curva de aprendizaje requiere de tiempo y dedicación (como en todo), la verdadera dificultad a mi manera de ver es la utilización de los convertidores y las platillas de estilo que permiten que el documento XML creado se convierta en un lindo y hermoso PDF o en una atractiva página HTML. 

Además DocBook es la elección para documentar de muchos de los proyectos más importantes de Software Libre tales como: Apache, Debian, Gnome, etc.

Este estándar se ha ido consolidando poco a poco en el mercado e iniciativas como la de Apache Velocity han desarrollado un DocBook Framework para que la curva de aprendizaje e instalación de un ambiente de desarrollo para documentar sea cosa más facil.

Un tutorial sobre cómo crear documentación con el DocBook Framework aquí.