Cómo documentar un sistema de software
Páginas: 12 (2806 palabras)
Publicado: 1 de diciembre de 2010
Objetivo
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 esimposible 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 eldesarrollo 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 deayuda 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 mostrarsereacios 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 siencuentra 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 queesto 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 boletín facilita directrices sobre cómo documentar un sistema de software como el proyecto 6.170. Proporciona una estructura esquemática y algunos elementos obligatorios, pero deja bajo su propio criterio todo lo referentea 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.
Puede cortar y pegar en su documentación el texto decualquiera de los boletines que le hemos facilitado. En concreto, es posible que quiera usar partes del boletín de problemas para describir los requisitos. No obstante, asegúrese de indicar claramente cualquier cambio que realice, ¡para que su ayudante técnico no tenga que emular manualmente el programa diff de Unix!
Esquema
Su documentación debería tener la siguiente estructura. Se facilita...
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 esimposible 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 eldesarrollo 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 deayuda 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 mostrarsereacios 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 siencuentra 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 queesto 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 boletín facilita directrices sobre cómo documentar un sistema de software como el proyecto 6.170. Proporciona una estructura esquemática y algunos elementos obligatorios, pero deja bajo su propio criterio todo lo referentea 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.
Puede cortar y pegar en su documentación el texto decualquiera de los boletines que le hemos facilitado. En concreto, es posible que quiera usar partes del boletín de problemas para describir los requisitos. No obstante, asegúrese de indicar claramente cualquier cambio que realice, ¡para que su ayudante técnico no tenga que emular manualmente el programa diff de Unix!
Esquema
Su documentación debería tener la siguiente estructura. Se facilita...
Leer documento completo
Regístrate para leer el documento completo.