Suficientemente simple documentación, pero no tan simple

Uno de los valores ágiles dice Software Funcionando sobre Documentación Extensiva. He visto que en algunos proyectos esto es una justificación para no generar documentación en un proyecto. Sin embargo, lo que dicen las metodologías ágiles es «Keep Documentation Just Simple Enough, but not Too Simple», «Mantener la documentación lo suficientemente simple, pero no tan simple».

La documentación integral no asegura el éxito de un proyecto. La documentación debería ser concisa, la información general y los flujos es generalmente preferido a la información detallada.

La mejor documentación es la que en su simplicidad permite que el trabajo se haga. No creemos un documento de 20 páginas cuando un documento de 2 páginas servirá. O crear un documento de 2 páginas cuando 2 bullets funcionaran. Evitar repetir información cuando se pueden usar referencias. Documentar solamente lo que será útil.

¿Qué información será útil documentar y para quien?

Según mi experiencia, hay tres roles importantes en los que es necesario enfocarse:

  1. Nuevos Products Owners que ingresaran al proyecto: Aparte de tener un enlace a la aplicación o una aplicación móvil en el store, es importante tener información de los flujos principales, esto puede ser en gráficos, pero con una explicación.
  2. Nuevos desarrolladores que ingresaran al proyecto: Necesitan la misma información que el rol anterior para entender el porqué de la aplicación y a su vez necesitan tener bien documentado el código, con la información justa y necesaria para comprender el porqué de las cosas.
  3. Stakeholders: Igualmente es necesario que tengan todo actualizado, porque es información importante que puedan querer compartir con partners o usuarios.

Es importante mantener toda esta documentación actualizada. Generalmente tenemos las primeras versiones de nuestros documentos, pero con el paso del tiempo, hay cambios en nuestra aplicación y estos documentos no son actualizados. Finalmente, cuando alguien quiere conocer el estado actual de la aplicación, debe sumergirse en las historias de usuario y hacer un timeline de lo que sucedió. Cabe mencionar que no necesariamente tenemos que reescribir la historia en el mismo flujo o documento, pero podemos hacer una referencia a esta, para poder acceder a la información rápidamente.

De los proyectos en los que he participado he aprendido que este tema puede retrasar muchos proyectos. Especialmente los que tienen largo tiempo y han pasado por muchas personas. El ingreso de alguien nuevo siempre va a cambiar el ritmo del proyecto. Sin embargo, el estar entendiendo las cosas por prueba y error, asumiendo o incluso preguntándole al cliente, hace que este paso demore más.

Referencias: Best Practices for Agile/Lean Documentation

Deja un comentario