El Proceso Unificado Ágil: modelos y documentación

En la primera entrega comenté las distintas fases que distingue el Proceso Unificado Ágil. Y en ésta, y para terminar, hablaremos de los modelos y documentos que existen en AUP, y cómo se encuadran en el modelado ágil.

Desde este punto de vista, un documento es “cualquier artefacto externo al código fuente cuyo propósito sea transmitir información de una manera persistente”. Esto plantea algunas diferencias con el concepto de modelo, que se define como “una abstracción que describe uno o más aspectos de un problema o una solución potencial a un problema”. El siguiente diagrama describe cómo se relacionan estos conceptos entre sí:

En general, algunos modelos terminarán siendo documentos o partes de documentos, y otros podrán simplemente ser descartados tras haber cumplido su función. El ciclo de vida de un modelo ágil vendría a ser:

Si no todos los modelos ágiles se conservan como parte del sistema, ¿cuándo se puede considerar un modelo como permanente? En general, cuando cumpla los siguientes requisitos:

  • Hay una razón clara y valiosa para hacerlo permanente.
  • Hay alguien para quien el modelo es importante.
  • Los promotores lo requieren.

Respecto a la documentación, considerada parte intrínseca y necesaria del sistema por la metodología, se propone un enfoque ágil y centrado en mantenerla lo más ligera posible, en parte debido al coste añadido que implica mantenerla actualizada.

Para el Proceso Unificado Ágil, hay algunas razones válidas para crear documentación, resumidas en la siguiente lista:

  • Los promotores del proyecto lo requieren.
  • Para definir un modelo de contrato.
  • Como ayuda a la comunicación con un grupo externo. Sin embargo, la documentación no debería ser el medio de comunicación principal.
  • Como soporte a la memoria organizacional. No sólo se necesita desarrollar el software, sino que es necesario contar con documentación apropiada para su uso, soporte técnico y mantenimiento a lo largo del tiempo.
  • Para labores de auditoría.
  • Para ayudar a pensar sobre algo. El simple acto de escribir ideas en un papel puede contribuir a consolidarlas y a descubrir problemas en ellas.

En relación con la elaboración de documentación, en la metodología se exponen algunos puntos críticos y recomendaciones que se considera conveniente reproducir:

  • Lo fundamental es la comunicación, no la documentación.
  • La documentación debe escribirse si es la mejor manera de alcanzar los objetivos relevantes, aunque con frecuencia hay mejores maneras de alcanzar estos objetivos que escribir documentación estática.
  • Documente elementos estables, no especulaciones.
  • Tome un enfoque evolutivo sobre el desarrollo de documentación.
  • Prefiera artefactos ejecutables como pruebas de aceptación y de desarrollo sobre otros estáticos.
  • Debe entender el coste total de propiedad (Total Cost of Ownership, TCO) para cada documento.
  • La documentación bien escrita es útil como soporte a la memoria organizacional, pero es una pobre manera de comunicar en un proyecto.
  • La documentación debería ser concisa: resúmenes y hojas de ruta son generalmente preferibles sobre otro tipo de documentación detallada.
  • Con un código fuente de alta calidad y un conjunto de pruebas para respaldarlo, no necesitará demasiada documentación.
  • Viaje tan ligero de equipaje como pueda. Cada artefacto que crea y que decide mantener necesitará ser mantenido a lo largo del tiempo. Cada vez que resuelve mantener un modelo sacrifica agilidad a cambio de conservar esa información disponible para su equipo de una manera abstracta. No subestime la importancia de este sacrificio .
  • La documentación debería ser sólo tan buena como sea necesario.
  • La documentación comprensiva no asegura el éxito del proyecto. De hecho, incrementa las probabilidades de fracaso.
  • Los modelos no son necesariamente documentos, y los documentos no son necesariamente modelos.
  • La documentación forma tanta parte del sistema como el código fuente.
  • El objetivo principal de su equipo es desarrollar software, el objetivo secundario es facilitar su siguiente esfuerzo.
  • El beneficio de tener documentación debe ser mayor que el coste de crearla y mantenerla.
  • Los desarrolladores rara vez confían en la documentación, particularmente en la documentación detallada, porque generalmente no está actualizada con respecto al código.
  • Cada sistema tiene sus propias necesidades de documentación.
  • Pregúntese si necesita la documentación, no si la quiere.
  • La inversión en documentación del sistema es una decisión de negocio, no una decisión técnica.
  • Cree documentación sólo cuando la necesite en el punto adecuado del ciclo de vida.
  • Actualice la documentación sólo cuando duela. Debería actualizar un modelo sólo cuando lo necesite. Es decir, cuando el hecho de no contar con un modelo actualizado sea peor que el esfuerzo de actualizarlo.

Entregables

Respecto a los entregables, el Proceso Unificado Ágil distingue entre:

  • Entregables. Que deben ser producidos como parte permanente del sistema.
  • Otros productos de trabajo del proyecto que pueden descartarse porque no se desea mantenerlos a lo largo de la vida del sistema.
  • Productos de trabajo de la organización, que serán mantenidos por el departamento de desarrollo y compartidos con el resto de proyectos.

Asimismo, la metodología propone las siguientes recomendaciones en relación a la documentación entregable:

  • Mantenga los productos de trabajo tan simples y concisos como sea posible.
  • Necesita mucha menos documentación de la que cree.
  • Trabaje cerca de la gente que va a crear un producto de trabajo de manera que sólo produzcan lo que necesiten.
  • Los documentos ágiles son sólo tan buenos como requiera la tarea en cuestión.
  • Producir un documento es la peor manera de comunicar información. Varias personas alrededor de una pizarra blanca es la mejor.
  • Use herramientas simples como pizarras blancas, papel y wikis para modelar y capturar documentación.
  • Considere adoptar plantillas libres como base para crear sus propias plantillas.

La siguiente tabla describe, en orden de prioridad, los entregables mínimos para un proyecto basado en el Proceso Unificado Ágil:

Entregable

Descripción

Recomendaciones

Sistema

El software, hardware y documentación que deben ser desplegados y puestos en producción.

El sistema no es sólo el código que se escribe.

Código fuente

El código del sistema.

Seguir convenciones de codificación comunes.

Conjunto de pruebas de regresión

Colección de casos de pruebas, y el código para ejecutarlos en el orden apropiado. El conjunto de pruebas de regresión debería incluir pruebas de aceptación, pruebas unitarias, pruebas del sistema…

Automatizar las pruebas y ejecutarlas con tanta frecuencia como sea posible, idealmente cada vez que algo cambie.

Scripts de instalación

Código para instalar el sistema en el entorno de producción.

Es conveniente disponer de uno o varios scripts para instalar y desinstalar el sistema en producción.

Documentación del sistema

La documentación entregada como parte del sistema para ayudar a los usuarios a trabajar con él y a los desarrolladores a mantenerlo. Generalmente se compone del manual de operaciones, documentación de apoyo, manuales de usuario y descripción general del sistema.

Mantener la documentación tan ligera como sea posible.

Notas de la versión

Resumen de los puntos importantes sobre la versión actual del sistema.

Algunas notas en forma de lista son suficientes en general.

Modelo de requisitos

Describe los requisitos que el sistema debería contemplar. Comprende una gran variedad de productos de trabajo, incluyendo potencialmente pruebas de aceptación, posibles automatismos, procesos y reglas de negocio, modelo del dominio, modelo de la organización, glosario, requisitos técnicos, modelo de casos de uso y modelo de la interfaz de usuario.

El objetivo es entender y después construir lo que los clientes necesitan, no escribir montones de documentación.

No es necesario conservar todos los aspectos del modelo de requisitos, sólo las partes que ayuden a entender el alcance del proyecto. En concreto, puede ser interesante mantener: los diagramas de procesos de negocio, el glosario, los test de aceptación y la descripción de algunos casos de uso.

Modelo de diseño

Describe el diseño del sistema. Comprende cierta variedad de artefactos, potencialmente un modelo de despliegue, un modelo de objetos, un modelo de datos, un modelo de amenazas de seguridad, el documento de resumen o vista general del sistema y un modelo de la interfaz de usuario.

Es preciso mantener los modelos de diseño tan simples como sea posible, y descartar todos los modelos que se pueda una vez se haya obtenido valor de ellos.

El mejor lugar para documentar el diseño son las pruebas unitarias y el código fuente.

Se debería conservar el documento de resumen del sistema y el modelo de datos para la documentación permanente. También pueden conservarse algunos diagramas importantes, como diagramas de secuencia o de máquina de estados.

Y eso es todo :-)

One thought on “El Proceso Unificado Ágil: modelos y documentación”

Leave a Reply

Your email address will not be published. Required fields are marked *