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
