La difícil tarea de documentación

No llevo mucho tiempo en el mundo de la informática, desde 1998 a la fecha, unos 11 años de los cuales 7 son ejerciendo como profesional el desarrollo de software. Y lo más difícil para un programador es documentar el software que ha desarrollado. Esta tarea es pesada y tediosa, por lo que muchas veces cuando concluimos el desarrollo de la aplicación, nos olvidamos de la documentación del mismo (ni siquiera los xml que son generados por los mismos IDE de desarrollo de hoy en día).

Muchas empresas contratan un personal solo para que realice esta tarea (excelente, un persona que desarrolla no puede documentar también, ya que una de las tareas se queda inconclusa o mal), pero en los países latinoamericanos como República Dominicana, el desarrollador tiene que hacerlo todo, analizar el proyecto, realizar el levantamiento del mismo, desarrollarlo, auditarlo, ponerlo en marcha y si, "eso mismo que están pensando", documentarlo.

Para eso, les voy a dejar unos cuantos consejos de que medidas tomar para entregar software con una documentación clara y coherente de como funciona o como está diseñado.

Primero: Defina los proceso, las actividades y las tareas que va a ejecutar su programa. Luego de definir estos procesos y tareas, se debe eleborar un diagrama donde se muestre el funcionamiento del software.

Segundo: trate de ir documentando todas las variables, funciones y procedimientos que declara en su proyecto, esto lo ayudará bastante a la hora de generar su XML y posterior su documentación (puede utilizar programas como NDoc, SandCastle, entre otros para Visual Studio y JavaDoc para Java, entre otros, dependiendo del lenguaje que utilice). Nota: Al momento de documentar es vital que se escriba en tercera persona identificando quien realiza la acción, ejemplo: el sistema, el módulo, etc. Utilizar los verbos en presente, sin usos de gerundios.

Esta parte es la que se conoce como documentación técnica, y es la que debe entregarse a los auditores de sistemas y otros programadores que tengan que desarrollar sobre la plataforma que usted ha creado. Este tipo de documentación no está orientada a usuarios finales por lo que no es necesario que se encuentre muy estructurada y comprensible.

Tercero: luego de tener su software técnica lista, se deben imprimir las pantallas paso a paso de como debe funcionar el sistema para ser utilizadas en la documentación de usuario final.

Cuarto: elaborar una documentación con los requerimientos de hardware necesario para el correcto funcionamiento de su sistema (Cantidad de memoria, procesador, espacio en disco) y otra con los requerimientos de software (componentes de terceros necesarios para el correcto funcionamiento de la aplicación, sistema operativo, entre otros)

Luego de tener los requerimientos de hardware y software y las capturas de las pantallas con el funciomiento del sistema o módulo paso a paso, se debe pasar a elaborar la documentación completa del sistema, explicando en un lenguaje sencillo y comprensible como funciona la aplicación. En este punto, se debe tratar de eliminar los términos técnicos de programación (un error que cometemos frecuentemente los desarrolladores).

El documento debe estar bien ordenado y estructura de acuerdo de una estructura jerárquica de hipertexto que mida la compactación del documento y el grado de organización del mismo.

La presentación de la documentación es muy importante, en la misma se deben tomar en cuenta los siguientes puntos:

• Título o nombre del software
• Compañía
• Derechos de Copia Legal
• Versión del producto
• Fecha de revisión

Ojo, para aquellos que desarrollan software libres, deben tener el cuenta el tipo de licenciamiento, como son los GNU GPL, entre otras, para más imformación ver. Además, no olvidar las famosas cuatros (4) libertades de la licencia GPL que caracteriza el sistema operativo libre: El software se puede usar, el software se puede modificar, el software se puede distribuir y el software se puede distribuir ya modificado.

Para los gustos los colores, y el tipo de software que desarrolle va a influir en el tipo de documentación que va a entregar, pero nunca olvide, el software tiene una intención fundamental: usarlo y mientras más sencillo es, más fácil será su acogida por el público.