Documentación en proyectos ágiles – Mitos, respuestas y alternativas superadoras

Un tema complejo el de la documentación.

Muchos piensan que el manifiesto ágil incita a los equipos a no documentar, debido al segundo de los 4 valores: Software funcionando sobre documentación extensiva. Esto es falso, es un mito. Se puede documentar todo lo que realmente sea necesario.

Lo difícil radica en que siempre (estemos o no en un proyecto “ágil”) debemos preguntarnos para qué y para quién la haremos y analizar en cada caso, si es que realmente necesitamos documentos para cumplir esos objetivos.

Suelo recomendar el uso de gráficos y esquemas en las paredes del espacio de trabajo del equipo, con los temas importantes (ej: la arquitectura del proyecto, la infraestructura, las decisiones de diseño más importantes).

También puede ayudar el hecho de grabar videos con las explicaciones más complejas.

Estas dos primeras recomendaciones (gráficos y videos) serían útiles para asegurar la coherencia entre el diseño y la implementación de aplicaciones.

Otro tema importante en la documentación ágil son las pruebas automatizadas: Unitarias, de integración, funcionales, de aceptación, de performance…
Si ya las hacen, sabrán de qué hablo. De lo contrario, lo explicito: Las pruebas automatizadas tienen gran poder en cuanto a mostrar “qué hace la app” y “cómo lo hace“). Y además hacen más baratas las pruebas de regresión.

En cuanto a la capacitación de nuevos integrantes del equipo, nada peor que mandarlos a leer documentos. Suelen ser aburridos, fueron hechos casi siempre con un sesgo del autor, tienen partes ambiguas… (y una larga lista de etcéteras.)
Para resolver ese tema, recomiendo que usen programación de a pares (y pairing en general, para todas las actividades del equipo). Haciendo se aprende más rápido y mucho mejor, que leyendo documentación.

En cuanto a entender y comunicar requerimientos del sistema, creo que una buena User Story (Historia de Usuario) puede ayudar mejor que los Casos de Uso o Requerimientos tradicionales. En el libro de mi socio y amigo Martín Alaimo se explica este tema a la perfección.

Por último, quiero aclarar que conozco bastante bien el lenguaje de modelado unificado (UML) y creo que en muchas ocasiones es útil usar los diagramas de secuencia, de implementación (AKA deploy) y aquellos que el equipo requiera para entender mejor alguna situación compleja y/o repetitiva.

A modo de cierre: no creo que “ser ágil” implique “no documentar”. Sino que “ser ágil” implica siempre estar atento y crítico con todo el proceso de desarrollo. Todo es perfectible y la clave está en encontrar el balance y el equilibrio adecuado. Un buen primer paso puede ser analizar las opciones de mejora que estén a nuestro alcance, en el camino entre lo que hacemos ahora y la/s mejor/es alternativa/s posibles.

“Capacitación” (Not!)

Anuncios

6 pensamientos en “Documentación en proyectos ágiles – Mitos, respuestas y alternativas superadoras

  1. Gracias a mi tocayo Pablo Vázquez, de la comunidad chileagil, por preguntar en la lista de correo comunitaria al respecto de este tema. Su pregunta originó mi respuesta. Y de ese texto a este artículo, hubo sólo un copy+paste de distancia, y algunos agregados y modificaciones menores 🙂

  2. En algunos proyectos la documentación también puede ser vista como parte del producto a entregar, pero claro, no descuidando la mirada de lo que tu mencionas, ¿cuánto valor nos aporta como equipo y para el cliente?

    Algo que me gustaría recalcar es lo mencionado al final, el ser crítico con todo el proceso de desarrollo, pues es muy provechoso evaluar entre los generadores y los destinatarios, los artefactos documentales (llámense dibujos, videos, diagramas, etc.) utilizados en el proceso de desarrollo y como pueden potenciarse/mejorarse y apoyar a la comunicación directa.

  3. Hay una observación de Booch respecto de la documentación: Afirma que un desarrollador aficionado siempre busca la magia; algún método o herramienta sensacional que garantize que el proceso de desarrollo de software sea trivial. Este tipo de profesional desecha la documentación en absoluto o bien sigue un proceso dirigido por la documentación. A mi entender, lo que sería más apropiado documentar es la arquitectura del sistema en sus aspectos estáticos y/o dinámicos; esto es, las decisiones más relevantes de la misma. Si estamos haciendo un edificio, no tendría sentido no hacer ningún tipo plano como así tampoco hacer el plano de la composición química de cada ladrillo. A mi entender, el arquitecto del proyecto juega un rol clave en la decisión de que cosas es necesario documentar y que no puesto que dispone de los conocimientos técnicos y del negocio que le proporcionan un criterio válido a la hora de tomar una decisión de este tipo.

    • Gracias por tus observaciones, Lautaro! Me parecen muy valiosas.

      En mi forma de ver los equipos ágiles, lo que vos considerás como parte del rol del arquitecto (decidir qué se documenta y en qué nivel) debería ser una responsabilidad del equipo. De haber un (1) arquitecto, éste debería aplicar este criterio *y también* socializarlo, para que se difunda y que se complemente con los conocimientos de los demás integrantes del equipo (negocio, programadores, testers, infraestructura, seguridad, etc etc).

      Saludos, y nuevamente gracias por tu comentario!

  4. Hola. Actualmente me encuentro desarrollando sola. Tengo que documentar lo que voy desarrollando, el problema es que la documentación es extensa y para algo más ágil no existe un procedimiento que me indique qué colocar y qué descartar. Muy buen post, creo que el uso de esquemas es lo mejor para explicar. Ahora, el tipo de esquemas va a depender justamente de qué quiero explicar (grandes o pequeños rasgos). Prefiero quedarme con la opción global al desarrollar de forma ágil.
    Saludos!

    PD: Lindo cabello 😀 pablotortorella

Comentarios, Ideas, Críticas constructivas, Feedback?

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s