No recuerdo que, cuando estudiaba, nada me hablara nunca de la Documentación Técnica. De hecho, en el Proyecto Fin de Carrera (lo más parecido a un proyecto real que se hacía), recuerdo como entregables cosas como la Especificación de Requisitos, el Análisis, el Diseño, los Fuentes y el Manual de Usuario, pero nada de Documentación Técnica...
Fue al empezar a trabajar cuando me enteré de que, después de hacer un programa (en RPG), se esperaba de mí que creara (o modificara... que como programador nuevo uno no hacía muchos programas nuevos) un documento de Word explicando los detalles internos del programa (algo de pseudocódigo, descripción de las validaciones, diseño de pantallas, ejemplos de llamadas...). La creación y mantenimiento de este tipo de documentación rivalizaba con la Documentación de Usuario por el premio a la tarea menos deseada de todo el proceso de desarrollo.
Más o menos por esa misma época (quizá un año antes...), oí hablar en un cursillo de Java por primera vez de una herramienta que hacía algo muy curioso: javadoc. Que a partir del código fuente y una serie de comentarios especiales, se pudieran generar automáticamente una serie de documentos HTML describiendo la estructura y detalles de las Clases empleadas, con el mismo formato que la propia ayuda estándar de Java, parecía casi cosa de magia.
A la primera versión de la Documentación Técnica reconozco que le veo poca utilidad: no deja de ser un duplicado del código fuente en un formato más legible. Aún asumiendo que el RPG es un lenguaje poco legible (o menos legible que otros, que no se me enfade nadie...), lo que se logra con esta documentación no es nada que no pueda lograrse con unos comentarios apropiados en los fuentes. Si es por un problema de acceso a los fuentes (era más fácil acceder a los documentos Word que a los fuentes de un programa RPG), hubiera visto más práctico generar automáticamente un listado de texto de los fuentes RPG cada vez que se pone un programa en producción. En todo caso, el peor problema de este tipo de Documentación Técnica es el de mantener sincronizadas las versiones de los fuentes y los documentos. Tarde o temprano, un documento se va a quedar desactualizado y examinarlo no va a servir de nada y no va a haber más remedio que acabar acudiendo a los fuentes.
Más útil es la segunda versión comentada de la Documentación Técnica, generada automáticamente. Quizá no lo sea tanto para uso interno, pero sí en entornos más "compartimentalizados" en los que se proporcionen componentes o librerías a otros grupos de desarrollo (o, evidentemente, si se desarrolla ese tipo de software para el usuario final). Así, nuestros clientes pueden usar nuestros componentes con el apoyo de una buena ayuda, y sin necesidad de acceso a nuestros fuentes: una situación idealmente perfecta.
Las ventajas de este tipo de documentación son principalmente dos. La primera es que se apoya en la que debería ser la principal fuente de documentación y resolución de dudas para el desarrollador: los comentarios del propio código fuente. Puede parecer una perogrullada, pero vale la pena repetirlo y destacarlo: la mejor Documentación Técnica es el código fuente (comentado adecuadamente). Evidentemente, esto obliga a desarrollar una disciplina a la hora de programar y comentar. Esto debería tenerse ya, pero la necesidad de crear unos comentarios que deban ser "compilados" por un sistema automático lo que logra es reforzar la necesidad de esa disciplina. Por duro que se haga comentar el enésimo método de acceso a una propiedad (El método getDato sirve para obtener el valor del dato...), vale la pena hacer el esfuerzo y acostumbrarse a dejar todo documentado: se gana en claridad y en tranquilidad. Si algo no está documentado ya no cabe la duda de si se debe a que es muy trivial o se trata de un olvido: ya no existe nada trivial.
El segundo punto a favor de estos métodos automáticos de documentar es, precisamente, que son automáticos. La generación de documentación se convierte así en un paso más del proceso de desarrollo, como el compilar para generar un ejecutable. ¿Qué inconvenientes se le puede poner a un sistema que automatiza la realización de una tarea que se considera desagradable? Ahora mismo no se me ocurre ninguna...
En resumen, la generación automática de Documentación Técnica permite generar fácilmente uno de los entregables que se le exigen al desarrollador, con el efecto secundario de reforzar la disciplina a la hora de comentar el código fuente. Todo son ventajas.
Así, aunque no se programe en Java, vale la pena buscar algún sistema similar a javadoc, por no hablar que la mayoría de lenguajes y entornos "modernos" (de Python a .NET) ya incluyen este tipo de herramientas. Y si no, es posible que existan de manera independiente. Ahora mismo trabajo en un proyecto desarrollado en Visual C++ (eMbedded) y empleo DoxyS para generar periódicamente la documentación de unas 200 Clases con un total de alrededor de 100.000 líneas de código. Es un programa sencillo (seguro que los hay más configurables y flexibles) para la sintaxis que requiere es muy poco intrusiva y lo que produce es más que suficiente para mis necesidades. Para hacer frente a algunas de sus carencias más problemáticas he programado unos scripts en Python para "preparar" los fuentes antes de llamar a la generación de la documentación. El resultado final es que, tras unos 20 minutos de procesamiento, se dispone de la Documentación Técnica de mi proyecto en un servidor web. La documentación es totalmente navegable, buscable, y va desde gráficos de llamadas de más alto nivel hasta la posibilidad de consultar el código fuente de un método concreto. Y todo eso sin más que ejecutar una sentencia en la línea de comandos: ¿qué más se le puede pedir?
