Dentro de un contexto ágil, hay un foco importante en el dimensionamiento adecuado de la documentación.
Se debe dar respuesta a la burocracia que ha dado lugar a grandes volúmenes de documentos de proyectos y productos que a menudo se quedan sin leer, están desactualizados cuando se han completado y parecen tener poco valor para el equipo. Por otro lado, hay personas que en un contexto ágil dicen que no es necesaria ninguna documentación. La verdad está en algún lugar en el medio.
Uno de los valores del agilismo es «working software over comprehensive documentation». Esto no quiere decir que no hay ningún valor para el elemento de la derecha, pero hay mucho más valor en el elemento de la izquierda. La clave de la derecha es el dimensionamiento de la documentación.
El dimensionamiento adecuado significa que:
- El nivel de esfuerzo aplicado a escribir y mantener la documentación más el valor de ese documento escrito, debe tener un mayor retorno de la inversión (ROI) que no tener esa información fácilmente disponible y tener que conseguirla (por ejemplo, el esfuerzo que se necesitaría para reconstruir la información y el impacto de no tener esa información disponible para las decisiones actuales).
Con esta idea se presenta una serie de propuestas sobre el correcto dimensionamiento de la documentación.
- La documentación debe ser viva y evolutiva. Se debe huir de la idea de documento “final”.
- Se debe considerar la posibilidad de documentación a nivel de producto que se puede evolucionar de forma natural en cada versión del desarrollo del producto.
- La documentación debe asumir un carácter colaborativo. No debe ser escrito por una persona a la perfección, y luego compartida con otros. En su lugar, debe ser compartida con frecuencia durante el desarrollo para enriquecerse con diferentes perspectivas.
- Actualizar la documentación de forma continua según se aprenden nuevas cosas. Si nos enteramos de algo que puede afectar al equipo o ayudar con la toma de decisiones, ir al documento y actualizarlo.
- Centrarse en una buena documentación suficiente y evitar grandes detalles por adelantado lo que generalmente significa evitar perder una gran cantidad de tiempo en adivinar. Se debe documentar lo que se sabe actualmente. Si ya no se necesita el documento, es razonable retirarlo.
- Se debe ser conciso. Se debe evitar una prosa demasiado espesa que puede hacer perder la atención de los lectores.
- La documentación puede adoptar muchas formas. No es sólo un documento de Word, la documentación puede vivir en un wiki, en el instrumento de planificación, como comentarios en el código, etc.
- Se deben documentar las decisiones. Conocer las decisiones ayuda a aquellos que deben mantener el producto y entender por qué las cosas se decidieron o hecho de una manera determinada.
- Hay que tener clara la diferencia entre la documentación interna y externa de documentación. Un Documento externo puede ser una guía de usuario o cualquier documento que se entrega al cliente. Estos deben considerarse como «working software» y tratarlo como parte fundamental del producto.
Finalmente, podemos distinguir tres tipos de documentos:
- Persistentes, documentos vivos (requisitos, pruebas de certificación, muy breves descripciones de arquitectura de alto nivel, manual de usuario, manual de explotación), que proporcionan un valor suficiente para ser mantenido en el futuro. Estos documentos deben formar parte de la Configuración del Producto, se deben registrar en el Plan de Gestión de la Configuración del Producto (que no en la gestión de la configuración del proyecto).
- Documentos transitorios que son útiles en el contexto de una release, que vale la pena guardar como referencia para la toma de decisión en el momento, pero no vale la pena el esfuerzo por mantener en el futuro.
- Los documentos que se pueden generar directamente desde el código, base de datos, etc.