¿Cómo documentar un sistema de software?

     Un sistema pobremente documentado carece de valor aunque haya funcionado bien en alguna ocasión. En el caso de programas pequeños y poco importantes que sólo se utilizan durante un corto periodo de tiempo, unos cuantos comentarios en el código podrían ser suficientes. No obstante, la mayoría de los programas cuya única documentación es el código, se quedan obsoletos rápidamente y es imposible mantenerlos. El que la dedicación de un poco de esfuerzo a la documentación sea recompensado incluso dentro de los límites de un pequeño proyecto, constituye una sorpresa para la mayoría de los novatos.

     A menos que usted sea infalible y viva en un mundo en el que nada cambia, tendrá que volver a consultar el código que ya está escrito, y pondrá en duda decisiones que tomó durante el desarrollo del mismo. Si no documenta sus decisiones, se verá siempre cometiendo los mismos errores y tratando de comprender lo que pudo haber descrito fácilmente en una ocasión. La falta de documentación no sólo genera trabajo adicional, sino que también tiende a dañar la calidad del código. Si no posee una nítida caracterización del problema, es imposible que desarrolle una solución clara.

    Aprender a documentar software es una tarea complicada y exige un criterio de ingeniería maduro. Documentar de forma concisa es un error habitual, pero el otro extremo puede resultar igual de perjudicial: si escribe documentaciones extensas, éstas atosigarán al lector y constituirán una carga a la hora de conservarlas. Es esencial documentar sólo los asuntos correctos. La documentación no sirve de ayuda para nadie si su extensión desanima a la gente a la hora de leerla.

     Los principiantes tienen la tentación de centrar sus esfuerzos en temas sencillos, ya que éstos les resultan más fáciles de documentar. Esto es una pérdida de tiempo; no se aprende nada del esfuerzo y se termina escribiendo una documentación que es cualquier cosa excepto útil. Los principiantes también tienden a mostrarse reacios con los problemas de documentación. Esto trae consigo poca visión de futuro: si usted sabe que algún aspecto de su diseño no es del todo correcto, que alguna parte del problema no se ha aclarado o que es posible que parte del código tenga errores, ¡dígalo! Hará que el lector ahorre tiempo dándole vueltas a algo que aparentemente es erróneo, se acordará de dónde tiene que mirar si encuentra problemas y acabará teniendo una documentación más útil y honesta.

     Otro asunto es cuándo documentar. Aunque algunas veces es conveniente posponer la tarea de la documentación mientras se realizan experimentos, los programadores con experiencia suelen documentar de forma metódica incluso el código provisional, los análisis de un problema inicial y los borradores de un diseño. Ellos creen que esto hace que la experimentación sea más productiva. Además, dado que han tomado la documentación como hábito, les resulta normal documentar a medida que van avanzando.

     Este blog facilita directrices sobre cómo documentar un sistema de software. Proporciona una estructura esquemática y algunos elementos obligatorios, pero deja bajo su propio criterio todo lo referente a los detalles. Es esencial que no piense que la documentación es un asunto rutinario y aburrido; si lo hace, su documentación no servirá para nada y será penosa a la hora de leerla y escribir. Así que documente de forma consciente: pregúntese a medida que lo hace, por qué lo hace y si está empleando su tiempo de la forma más eficaz.

    

Esquema

    Su documentación debería tener la siguiente estructura. Se facilita un número de páginas orientativo; lo que presentamos a continuación son directrices, no un requisito:

 - Documentación de Requisitos

  - Documentación de Diseño

 - Documentación de Pruebas

- Reflexion 

- Apendice

- Documentación del Codigo

- Manuales de Usuario