La documentación de los programas es un aspecto sumamente importante, tanto en el desarrollo de la aplicación como en el mantenimiento de la misma. Mucha gente no dedica tiempo a esta parte del desarrollo y no se da cuenta de que pierde la capacidad de un mantenimiento sencillo y parte de su potencial de organización del código, de una manera más flexible y escalable. Incluso la documentación puede ayudarnos a reutilizar partes de la aplicación y sobre todo de los esquemas de diseño.

Claro que examinando el código podemos llegar a entenderlo, pero llevaría un tiempo proporcional al tamaño de la aplicación. Incluso si tú eres el que más adelante tienes que dar soporte a la aplicación, aunque hoy conozcas el código al dedillo, probablemente no será así en unos meses o años.

Qué es la documentación

La documentación, como su propio nombre indica, es todo tipo de información que ayuda a dirigir los esfuerzos del equipo de desarrollo y que además ayude a entender la arquitectura y diseño de la aplicación a lo largo del tiempo. De cara al cliente puede ser toda aquella información que le guíe a la hora usar la aplicación una vez entregada.

La documentación de un programa empieza a la vez que la construcción del mismo. De hecho, lo más normal es comenzar haciendo esquemas de las piezas del programa, funcionalidad, interfaces, etc. para que, en el momento que nos pongamos a programar, tengamos muy claro qué es lo que se va a desarrollar y cómo lo vamos a hacer.

La realización de la documentación no termina con la entrega de la aplicación, pues durante el mantenimiento es necesario actualizarla para reflejar los cambios que se hayan tenido que realizar para crear nuevas funcionalidades.

No confundir documentación con los comentarios del código

Es importante no confundir la documentación con los comentarios del código. En realidad un código debería de ser tan sencillo y claro que no requiera comentarios. Si tienes que comentar un código porque es demasiado complejo como para entenderlo leyendo, es que hay algo que estás haciendo mal.

Por tanto, se deben evitar a toda costa los comentarios al código y, en cambio, tenemos que conseguir programas que leyéndolos podamos entender perfectamente qué es lo que hacen.

Cuándo se hace la documentación

Mucha gente piensa que la documentación de un programa, al menos la que indica cómo se va a desarrollar, se tiene que realizar toda al principio. Luego eventualmente presentar algunas partes al cliente para que la valide y finalmente programar lo acordado.

Esto no es así. La documentación acompaña las distintas etapas del proyecto, que son iterativas y de mejora constante. Hay algunas partes de la documentación que sí se realizan al principio, como el modelo de dominio, que nos ayuda a aclarar cuál es el vocabulario del cliente y fija el conjunto mínimo de palabras que todos tendremos que usar al crear las piezas de software. Además ayuda a relacionar las distintas entidades que el programa debe manejar. Otros diagramas que pueden ayudar mucho a entender el problema y el flujo de acciones de la aplicación son los de casos de uso y los diagramas de estado.

Sobre todo al principio del desarrollo de una aplicación, donde lo recomendable es dedicar los esfuerzos a las partes más complejas o que representen los mayores retos para el equipo, es importante realizar diagramas de clases de aquello que vamos a desarrollar. De hecho, al realizar estos diagramas, en parte, ya estamos programando, aunque no con código. Luego, lo largo de las distintas fases del desarrollo, se irán creando nuevos módulos que pueden requerir nuevos diagramas. Sin embargo, a medida que el proyecto avanza, no será siempre necesario realizar documentación, pues seguramente estaremos trabajando en módulos más sencillos o los módulos responden a una arquitectura similar a la de otros ya existentes en la aplicación.

Qué diagramas incluye la documentación

Es un poco pronto para poder definir qué tipos de diagramas vas a necesitar, ya que estamos en un manual de iniciación a la programación, pero generalmente serán diagramas de clases y algunos diagramas de estado. Puedes necesitar eventualmente algún diagrama de objetos y algún diagrama de actividad o secuencia. Para la toma de requisitos tendremos diagramas de casos de uso y mockups de las interfaces. Generalmente todos estos diagramas los hacemos con UML, ya que es un lenguaje ampliamente adoptado en la industria, que todo el mundo entiende.

Si quieres profundizar en esta parte es interesante ver algún curso de UML o, mejor, apuntarte al Máster de Desarrollo de EscuelaIT, donde aprendemos UML sobre la marcha a lo largo de las distintas disciplinas del desarrollo.

Documentación ¿Sí o no?

Sobre la necesidad o no de hacer documentación podemos entrar en una discusión infinita. Hay equipos de desarrollo que no la hacen y sostienen que "el código es la mejor documentación". Es totalmente válida la opinión de estos profesionales, dado que un buen código es auto-explicativo, pero hay que ser muy bueno diseñando y programar con unos estándares de calidad extremos para que sea así.

Por lo tanto, si tuviéramos que decidir entre un mal código con excelente documentación o un código de calidad sin absolutamente nada de documentación, es muchísimo mejor un código de calidad, porque se podrá entender perfectamente. Sin embargo, no todos estamos a ese nivel, por lo que no nos vendrá mal un poco de ayuda gracias a la documentación. Paralelamente, hay que poner todos los esfuerzos necesarios para conseguir desarrollar como los ángeles para alcanzar el éxito y la excelencia en el desarrollo de software.

En contra de la documentación también se señala que a menudo se queda desfasada por culpa de los cambios de diseño realizados en el mantenimiento o durante el desarrollo. Si bien es cierto, esto se compensa con el cuidado de mantenerla actualizada, sí es verdad que es un trabajo que se agrega al proyecto.

A favor de la documentación se puede señalar que es mucho más fácil participar en reuniones de diseño si tenemos delante diagramas que nos indican visualmente las propuestas de clases sobre las que se pretende trabajar. Si una persona se incorpora al equipo de trabajo también le resultará mucho más sencillo empezar a aportar activamente al proyecto si tiene unos diagramas que le faciliten entender cómo se ha desarrollado esta aplicación.

Lamentablemente, hay que estudiar mucho más para poder entender qué es la documentación y tener experiencia para saber cuándo hacerla y cuando no, además de qué diagramas se deberían realizar.

Documentación entendida de manera tradicional en cursos de formación secundaria

A continuación voy a dejar algunas notas sobre cómo es la documentación, tal como la explican en la formación de secundaria de España. Quizás sirva para aclarar algunos puntos adicionales.

Tipos de documentación

La documentación se divide claramente en dos categorías, interna y externa:

Interna: Es aquella que se crea en el mismo código, ya sea en forma de comentarios o de archivos de información dentro de la aplicación. Externa: Es aquella que se escribe en cuadernos o libros, totalmente ajena a la aplicación en sí. Dentro de esta categoría también se encuentra la ayuda electrónica. Qué documentos incluye la documentación

La guía técnica

En la guía técnica o manual técnico se reflejan el diseño del proyecto, la codificación de la aplicación y las pruebas realizadas para su correcto funcionamiento. Generalmente este documento esta diseñado para personas con conocimientos de informática, generalmente programadores.

El principal objetivo es el de facilitar el desarrollo, corrección y futuro mantenimiento de la aplicación de una forma rápida y fácil.

Esta guía está compuesta por tres apartados claramente diferenciados:

• Cuaderno de carga: Es donde queda reflejada la solución o diseño de la aplicación. Esta parte de la guía es únicamente destinada a los programadores. Debe estar realizado de tal forma que permita la división del trabajo
• Programa fuente: Es donde se incluye la codificación realizada por los programadores. Este documento puede tener, a su vez, otra documentación para su mejor comprensión y puede ser de gran ayuda para el mantenimiento o desarrollo mejorado de la aplicación. Este documento debe tener una gran claridad en su escritura para su fácil comprensión.
• Pruebas: es el documento donde se especifican el tipo de pruebas realizadas a lo largo de todo el proyecto y los resultados obtenidos.

Pero en todo caso, la documentación que se entrega al cliente tendrá que coincidir con la versión final de los programas que componen la aplicación.

Una vez concluido el programa, los documentos que se deben entregar son una guía técnica, una guía de uso y de instalación.

La guía de uso

Es lo que comúnmente llamamos el manual del usuario. Contiene la información necesaria para que los usuarios utilicen correctamente la aplicación.

Este documento se hace desde la guía técnica pero se suprimen los tecnicismos y se presenta de forma que sea entendible para el usuario que no sea experto en informática.

Un punto a tener en cuenta en su creación es que no debe hacer referencia a ningún apartado de la guía técnica y en el caso de que se haga uso de algún tecnicismo debe ir acompañado de un glosario al final de la misma para su fácil comprensión.

La guía de instalación

Es la guía que contiene la información necesaria para implementar dicha aplicación. Dentro de este documento se encuentran las instrucciones para la puesta en marcha del sistema y las normas de utilización del mismo.

Dentro de las normas de utilización se incluyen también las normas de seguridad, tanto las físicas como las referentes al acceso a la información.

Conclusión

Espero no haber divagado demasiado y que estas notas hayan sido de utilidad para los que estáis aprendiendo. Quizás se nos ha quedado muy en el aire todas estas ideas y necesitaríamos verlas con calma, con ejemplos, pero creo que en el momento en el que nos encontramos del Manual de iniciación a la programación se nos queda un poco grande esta tarea.

A continuación vamos a explicar algunas cosas sobre metodología que te puede ayudar en tus primeros pasos en el mundo de la programación.