Seguramente has oído el mito que “en entornos ágiles no se documenta”.
Aquí tienes un artículo donde te orientamos al respecto.
Ágil se refiere a un enfoque para el desarrollo de software que enfatiza el desarrollo rápido y flexible y la infraestructura de proyectos y procesos por su propio bien. La siguiente declaración muestra el «manifiesto» para el desarrollo de software ágil que ha servido desde 2001 como Desiderata del movimiento:
Individuos e interacciones sobre procesos y herramientas
Software funcionando sobre documentación extensiva
Colaboración con el cliente sobre negociación contractual
Respuesta ante el cambio sobre seguir un plan
Hay una variedad de metodologías ágiles
Hay muchas instancias metodológicas diferentes del enfoque ágil. Estos incluyen Programación Extrema, Scrum, Desarrollo Basado en Funciones y Crystal Clear. Las prácticas que aparecen en uno o más de los métodos ágiles incluyen lo siguiente:
- Historias del usuario. El texto especifica requisitos funcionales que describen las acciones de las personas.
- Desarrollo basado en pruebas. Los desarrolladores crean pruebas automatizadas al mismo tiempo que escriben el código probado.
- Iteracciones cortas. El plan de desarrollo consiste en breves iteraciones (unas pocas semanas); También se llama sprints.
- Programación en pareja. Los desarrolladores trabajan en parejas, donde uno está tipificando el código y el otro revisa el código buscando defectos y formas de mejorar el diseño.
- Refactorización. Como parte del ciclo de implementación, el código se refactoriza para mejorar la estructura interna y la capacidad de mantenimiento sin alterar el comportamiento visible desde el exterior.
Mitos y Conceptos Erróneos
Para algunos, la agilidad se usa como una excusa para evitar el desarrollo disciplinado. La figura siguiente representa esta visión temprana del mundo ágil:
Una idea errónea relacionada con el agilismo es que la codificación comienza el primer día del proyecto. En la práctica, la primera iteración puede pasar sin ningún código de producción escrito. Esto sucede porque el equipo está ordenando alternativas de diseño y realizando experimentos técnicos con diferentes marcos, plataformas o tecnologías.
El objetivo clave del diseño y modelado en proyectos ágiles no es evitar el diseño, sino evitar el «gran diseño por adelantado». Las estrategias de arquitectura amplias y de largo alcance se elaboran por adelantado, pero muchas otras decisiones de diseño se pueden diferir hasta que se necesiten.
«Una idea errónea relacionada con el agilismo es que la codificación comienza el primer día del proyecto.»
Principios de documentación
Las filosofías Views and Beyond y Ágil coinciden firmemente en un punto central: si no se necesita información, no la documente. Toda la documentación debe tener en mente el uso previsto y la audiencia, y debe producirse de manera que sirva a ambos. Uno de los principios fundamentales de la documentación técnica es «escribir para el lector». Eso significa comprender quién leerá la documentación y cómo la usarán. Si no hay audiencia, no hay necesidad de producir la documentación.
La selección de vista de arquitectura es un ejemplo de aplicación de este principio. El enfoque Views and Beyond prescribe la producción de una vista si y solo si aborda las preocupaciones de una comunidad de partes interesadas explícitamente identificada.
«Si no se necesita información,
no la documente.»
Otra idea central para recordar es que la documentación no es una actividad monolítica que detiene todos los demás avances hasta que se completa, sino la producción de la documentación se prescribe en etapas priorizadas para satisfacer las necesidades de las partes interesadas que la necesitan en un determinado momento, el truco es saber quiénes son los receptores y qué movimientos necesitan hacer.
Con esto en mente, el siguiente es el enfoque sugerido para producir documentación de arquitectura basada en Views and Beyond utilizando principios ágiles:
- Adopte una plantilla u organización estándar para capturar sus decisiones de diseño.
- Planifique documentar una vista si y solo si tiene un electorado de partes interesadas fuertemente identificado.
- Complete las secciones de la plantilla para obtener una vista de arquitectura cuando la información esté disponible. Pero solo haga esto si escribir esta información hará que sea más fácil (o más barato o que el éxito sea más probable) para alguien que está haciendo su trabajo.
Más allá de esta orientación estratégica, también puede usar los siguientes consejos:
- Deje de diseñar tan pronto como sienta que está listo para comenzar a codificar. No se preocupe por crear un documento de diseño arquitectónico y luego un documento de diseño más detallado. Produzca suficiente información de diseño que le permita pasar al código. Capture la información de diseño en un formato que sea simple de usar y fácil de cambiar, una wiki, tal vez. En el próximo sprint, puede expandir el diseño existente según sea necesario para capturar las decisiones de diseño necesarias para implementar las características enumeradas para ese sprint.
- No se sienta obligado a llenar todas las secciones de la plantilla, y ciertamente no todas a la vez. Todavía le sugerimos que defina y use plantillas ricas porque pueden ser útiles en algunas situaciones. Pero siempre puede escribir «N/A» para las secciones para las que no necesita registrar la información. En los equipos ágiles, el modelado a veces ocurre como breves discusiones en la pizarra. Más información sobre los elementos (catálogo de elementos), discusión de fundamentos (antecedentes de la arquitectura), mecanismos de variabilidad utilizados (guía de variabilidad) y todo lo demás se comunicará verbalmente al equipo, al menos por ahora. Más adelante, si descubre que es útil registrar una pieza de información sobre un elemento, un diagrama de contexto, la justificación de una determinada decisión de diseño u otra cosa, puede reemplazar el «N/A» con la información correspondiente.
- Si no vale la pena actualizar el diseño, deséchelo. Como ejemplo, suponga que creó un diagrama de secuencia que se convirtió en parte de la documentación de la arquitectura. En la implementación, se comenzó siguiendo lo que está en el diagrama de secuencia. Sin embargo, encontró mejores formas de implementar esa transacción y el resultado final resultó ser bastante diferente del diagrama de secuencia. El diagrama original cumplió su objetivo principal al guiar la implementación inicial. ¿Qué debe hacer con el diagrama ahora? Usted puede:
- Dejarlo como está. Esta es la peor opción, porque ahora la documentación estará en desacuerdo con la implementación. Nada hace que un lector huya de la documentación más rápido que el descubrimiento de que está desactualizado, y ahora el lector tampoco confiará en ninguna otra parte de la documentación de la arquitectura.
- Actualizar el diagrama. Esta es la opción ideal, el diagrama actualizado ayudará a los mantenedores que necesitarán comprender esa parte de la implementación.
- Eliminar o tachar el diagrama. Esta opción es la opción realista en muchos proyectos. El diagrama está desactualizado; es mejor que lo quite o lo marque como obsoleto o que ya no tenga autoridad para que no engañe a los lectores de la documentación. En los proyectos ágiles, el código, los comentarios de código y las pruebas unitarias asociadas a menudo sirven como documentación autorizada para diseños locales (específicos de elementos).
- Muchas veces, los bocetos son todo lo que necesitas. No pierdas el tiempo creando el diagrama más ordenado utilizando la última y más rica notación disponible. No gaste dinero en herramientas de modelado sofisticadas si solo necesita dibujar diagramas simples. En muchos proyectos ágiles, especialmente en aquellos con equipos pequeños y colocados, el verdadero valor de los diagramas de diseño proviene de dibujarlos, lo que lo obliga a pensar en los problemas; Una vez que se resuelven los problemas, la documentación se puede refinar. Muchas veces el diseño se representa como un boceto en una pizarra blanca o en una hoja de papel como en el siguiente ejemplo:
