Documentación de proyectos

16/09/2008

El proceso de documetación (históricamente vinculado al perfil del becario) de un proyecto aunque es en cierta medida un proceso automatizable, gracias a herramientas como PHPDoc, Javadoc, etc, es una tarea que se antoja tediosa y larga. Si a esta ecuación le añadimos variables como la extensión de la documentación, necesidad de distribuir la documentación en distintos formatos (html, pdf, etc), con distintos estilos y a través de distintos canales la cosa comienza a tomar un cariz oscuro.

Con este escenario en mente y sabiendo la relación 1 a 1 que existe entre las entidades Tiempo y Dinero es cuando comienza a tomar fuerza el uso de herramientas como Docbook, entre las ventajas que esta herramienta nos proporciona podemos citar algunas como:

  • Nos permite abstraernos del aspecto y centrarnos en el contenido.
  • Estilos personalizables.
  • Producción de contenidos en distintos formatos partiendo de un mismo fuente.

Por supuesto también tiene algunas desventajas, como:

  • Debemos superar la curva de aprendizaje que toda nueva tecnología nos impone.
  • Poca madurez en muchas de las herramientas libres.

A continuación presento un esquema que ilustra el funcionamiento de Docbook

Esquema de funcionamiento de docbook

Esquema de funcionamiento de docbook

La instalación de dockbook junto con los procesadores XSLT es sencilla, basta con seguir los siguientes pasos:

Instalamos los esquemas de docbook y las xsl

  1. apt-get install docbook-xml
  2. apt-get install docbook-xsl

Instalamos el procesador XSLT

  1. apt-get install xmlto

Instalamos el generador para pdf

  1. wget http://www.uniontransit.com/apache/xmlgraphics/fop/fop-0.94-bin-jdk1.4.tar.gz
  2. tar -xvzf fop-0.94-bin-jdk1.4.tar.gz
  3. mv fop-0.94 /opt
  4. ln -s fop-0.94 fop

Ahora si queremos, por ejemplo, generar un documento html,partiendo de un documento test.xml que sigue el formato docbook, haremos lo siguiente:

  1. xsltproc -o test.html /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl test.xml

Si en vez de un documento html queremos generar un pdf haremos esto otro:

  1. xsltproc -o test.html /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl test.xml
  2. /opt/fop/fop test.fo -pdf test.pdf
Invertir en conocimientos produce siempre los mejores beneficios. Benjamin Franklin
Anuncios