La documentación del software es una necesidad para alcanzar el éxito en los proyectos, pero a la vez es percibida por muchos desarrolladores y empresas como una fuga de tiempo productivo. ¿Hasta qué punto es importante documentar el software? ¿Dónde se encuentra la frontera entre la documentación necesaria y la documentación prescindible?
Un poco de historia del software y la documentación
A lo largo de la todavía corta historia del software se ha pasado por muchas etapas en las que la documentación se ha visto como algo imprescindible hasta algo indeseable. La clave está en los procesos de desarrollo y cómo la documentación ha ido pesando en cada etapa.
El antiguo proceso de cascada incluía primeramente un proceso de requisitado en el que se realizaba toda la documentación de la aplicación a realizar, junto con el diseño del software del proyecto. Cuando estaba totalmente definido aquello que se debía desarrollar. Entonces comenzaba la parte de la programación. En este proceso de desarrollo poco evolucionado se creaban biblias enteras de documentación con texto que al final nadie leía por completo. Además, como es imposible saber con total exactitud el alcance de los proyectos y todas sus aristas, era habitual que la documentación realizada no reflejase fielmente el desarrollo realizado finalmente.
Pasaron muchos años, a lo largo de varias etapas que vamos a saltar, hasta que llegaron las metodologías ágiles. Especialmente en un primer momento, la documentación podía pasar a un segundo plano, ya que en cada iteración se toman unos pequeños requisitos y no existe necesidad de documentar aquello que está en proceso de desarrollo. No obstante, sí existen diversos tipos de documentación de las aplicaciones, incluso en los procesos de desarrollo ágiles, en los que es importante especificar cuáles son las funcionalidades del software desarrollado, para permitir que, quienes que van a usar este software, puedan conocer sus posibilidades, algo sobre todo importante cuando los clientes del software son otras máquinas, como ocurre con los servicios web.
Retos de la documentación del software
La documentación es parte del software, necesaria para su correcto uso y mantenimiento. No obstante, realizarla no siempre es fácil, porque hay que saber qué documentar y cómo documentarlo. Son importantes puntos como los siguientes:
- La documentación debe evolucionar con el software. El software cambia con el tiempo y también lo debe de hacer la documentación, que sirva de reflejo fiel de la aplicación desarrollada. Una documentación obsoleta puede ser incluso contraproducente
- La documentación debe estar bien organizada y ser fácil de entender, además que requiere ser consultada de manera rápida. Por eso es preferible la creación de diagramas en lugar de textos.
- Los diagramas deben de ser entendidos de manera idéntica por todas las personas. Por ello es importante acudir a un lenguaje como UML, el cual indica el significado de cada uno de los elementos que forman parte de los diagramas
- En el caso de usar lenguaje escrito, debe ser claro y conciso, sencillo de entender incluso con menos conocimientos técnicos
- Además, debemos de proporcionar un grado de navegación dentro de la documentación, ser consistentes, saber a quién está dirigida, etc.
Mantener una documentación correcta y actualizada es una tarea que lleva tiempo y al desarrollar un proyecto es importante que se destinen los suficientes recursos para su realización.
Tipos de documentación
En el desarrollo del software existen dos tipos principales de documentación.
- La documentación que se refiere al proceso de desarrollo
- La documentación que aborda el producto
Vamos a ver con detalle estos tipos de documentación y establecer algunas pautas para cada uno de ellos.
Documentación del proceso de desarrollo
Durante el proceso de desarrollo del software es importante realizar una documentación adecuada para entender bien qué se debe programar y cómo se debe programar, más aún cuando el proyecto entraña cierta dificultad de desarrollo.
Algunos documentos que se realizan en esta etapa son:
- Requisitado: En este caso se realizan documentos para saber qué se va a desarrollar, indicando las funcionalidades de cada actor que interactúa con el sistema. La fase de requisitado puede incluir diagramas como los casos de uso, diagramas de los procesos de negocio, mockups de las interfaces.
- Planificación: Durante el proyecto es importante saber qué recursos vamos a destinar a cada tarea y cómo se van a organizar, los tiempos que se estima que cada etapa ocupará. Para ello son útiles los diagramas de Gantt, que generalmente se generan con el uso de alguna herramienta.
- Reportes del proceso de desarrollo: A medida que el desarrollo del proyecto se va realizando es esencial reflejar en un documento el rendimiento de nuestro equipo de desarrollo y el tiempo invertido en cada una de las disciplinas (gestión, análisis y diseño, programación, pruebas, despliegue). Llevar unas métricas de todo el proceso nos ayudará a ser conscientes de la inversión realizada, estimar de manera más exacta las necesidades y previsiones en adelante, de modo que cada vez sea más fiel el tiempo y dinero que un proyecto va a costar.
- Backlog de tareas: Es muy habitual que los equipos de desarrollo lleven herramientas que permitan saber qué tareas se deben realizar en cada proyecto y su urgencia, con un sistema ágil que ayude a decidir qué partes del proyecto se van a acometer en cada iteración. Para ello existen diversas herramientas del estilo de Trello que pueden ser muy útiles.
- Documentación del código: El código también se puede documentar con bibliotecas que permiten convertir los comentarios en documentos que pueden consultar los desarrolladores con facilidad. Cada lenguaje tiene sus propias herramientas para generar la documentación del código a partir de los comentarios, como Javadoc o PhpDocumentor.
Documentación del producto
La documentación del producto está especialmente dirigida a los usuarios finales de este producto y el personal que se dedicará a darle mantenimiento o prestar soporte. Estos documentos tienen mucha utilidad en el momento en el que nuevas personas se incorporan al proyecto, ya que les permite entender mejor las características del mismo y tener una idea concisa de las tareas que deben desempeñar.
Esta documentación incluye diversa información acerca de las funcionalidades de las aplicaciones, sus implementaciones y el modo de uso. Entre otros podemos encontrar los siguientes documentos:
- Descripción del sistema: Este documento puede guiar a las personas que van a gestionar una aplicación, indicando cuál es el objetivo de ésta, cuáles son sus requisitos funcionales, los requisitos no funcionales y las restricciones o necesidades especiales de las soluciones que se deben implementar.
- Guías de uso: Para los usuarios de la aplicación, donde especifique qué procesos se encuentran disponibles y cómo se deben usar las aplicaciones.
- Descripción del sistema: Para las personas más técnicas, que les ayude a entender la arquitectura de la solución, los sistemas que involucra y sus interacciones. Qué requisitos deben tener las máquinas de despliegue, en aspectos relacionados con la escalabilidad, seguridad y otros factores importantes que ayuden al correcto mantenimiento de los sistemas.
- Arquitectura del software: Si nuevos desarrolladores se incorporan al trabajo es importante tener una documentación sobre cómo está desarrollado el software y sus principales líneas de diseño y arquitectura. Generalmente con diagramas UML que permitan entender de una manera visual las diferentes piezas.
- Documentación del API: Además, si los clientes del software son otras piezas de software, como ocurre en el caso de las API o servicios web, es importante disponer de una completa documentación que especifique claramente la entrada y salida de cada proceso. En este caso herramientas como OpenAPI o Swagger son excelentes ya que nos permiten generar toda la documentación mediante anotaciones en el propio código.
En resumen
Esperamos que esta descripción de las necesidades y tipos de documentación te haya resultado de utilidad. Para finalizar queremos señalar de nuevo la importancia de realizar una correcta documentación del producto, que ayude durante el proceso de desarrollo del software y su mantenimiento a lo largo del tiempo. Esta documentación debe atender las necesidades de gestores, programadores y de los clientes finales del producto.
Además, tan importante como realizar la documentación es mantenerla actualizada, lo que lleva un tiempo considerable a lo largo de la vida útil de las aplicaciones. Este trabajo no debe olvidarse a la hora gestionar el proyecto, asignando los recursos suficientes para su realización.