Cuando el Manifiesto Agile declaró el principio de "Software funcionando sobre documentación extensiva" en 2001, los equipos de desarrollo se entusiasmaron con la idea de una nueva forma de trabajar.

La documentación pesada era el statu quo, pero también representaba un obstáculo para la eficiencia. Llevaba mucho tiempo crearla, dejaba poco espacio para las adaptaciones y requería un mantenimiento continuo. Esta simple línea del Manifiesto Ágil reconoció esos desafíos, y muchos equipos lo tomaron como una señal para despedirse de la documentación de una vez por todas.

Sin embargo, los equipos que dejaron de crear documentación por completo se enfrentaron a un nuevo conjunto de desafíos: tuvieron dificultades para compartir conocimientos, alinear las decisiones y el progreso, incorporar a nuevos miembros del equipo o solucionar problemas. Esos desafíos se han intensificado durante los últimos años, con el aumento del trabajo remoto.

Está claro que un desarrollo pesado y basado en la documentación no es eficiente ni eficaz, pero tampoco lo es eliminar la documentación por completo. Esto plantea la pregunta "¿cuál es el papel de la documentación en la metodología Agile?".

Para averiguarlo, hablamos con James Grenning, uno de los autores originales del Manifiesto Agile y el fundador de Wingman Software. En esta entrevista, Grenning comparte la intención que hay detrás de esa línea, que suele malinterpretarse en el Manifiesto Agile, y analiza cómo los equipos ágiles de hoy en día pueden lograr el equilibrio adecuado en la documentación para trabajar eficientemente.

Retrocedamos en el tiempo hasta la creación del Manifiesto Agile: ¿qué motivó esa reunión? 

James Grenning: En ese momento yo trabajaba con Bob Martin, y él me preguntó si quería participar en la conferencia de métodos ligeros en el Snowbird Ski Resort de Utah. Los métodos ligeros se referían a enfoques como programación extrema, desarrollo basado en funcionalidades y Scrum; todos ellos con un mínimo de ceremonias y artefactos en comparación con los enfoques más centrados en procesos que se habían impulsado en los años ochenta y noventa. 

Yo era partidario del enfoque de programación extrema (eXtreme Programming, XP), pero había expertos de cada una de las disciplinas de software ligero presentes en la conferencia. Aunque teníamos distintas trayectorias, compartíamos el deseo de mejorar las metodologías de desarrollo de software. Dijimos en broma que no queríamos que nos conocieran como los "pesos ligeros", así que otro objetivo era determinar un nuevo nombre, que es como llamamos hoy a Agile.

Hubo mucho debate y opiniones diferentes, tratando de encontrar las cuestiones en que podríamos estar de acuerdo. Soy ingeniero y esperaba hablar mucho de procesos técnicos, pero los temas principales fueron las personas y el trabajo en equipo. Esos temas se transformaron en declaraciones de valor. Priorizamos unos sobre otros, aunque dejamos en claro que los menos prioritarios también son valiosos. Así es cómo terminamos con los cuatro principios que se conocen hoy.

Realmente no esperaba que la gente le diera demasiada importancia al Manifiesto Agile cuando Ward Cunningham lo publicó en un sitio web, pero muchas personas se interesaron. Aunque me sorprendió, creo que demostró cuánta gente se sentía identificada con los retos del desarrollo de software y estaba ansiosa por mejorar su forma de trabajar. 

Analicemos una de las líneas del Manifiesto Agile con más detalle. ¿Cuál fue la intención original detrás de "software funcionando sobre documentación extensiva"? 

JG: La mentalidad en ese momento era: "Documéntalo primero, desarróllalo después", pero la documentación es costosa. No es solo un beneficio, sino también un costo.

Un objetivo de la documentación tradicional era obtener las solicitudes del cliente por escrito y acordar con el equipo de desarrollo por adelantado para que pudiera abocarse solo a esta tarea. El problema es que si los clientes hacen solicitudes de productos solo una vez al año, pedirán todo lo que se les ocurra, pero van a cambiar de opinión cuando se entregue el software.

Kent Beck, Ward Cummingham, Ron Jefferies y otros entusiastas de XP sabían que crear documentación de esta manera no solo consumía demasiado tiempo, sino que no le permitía al equipo incorporar aprendizajes o responder a los cambios. 

La línea "software funcionando sobre documentación extensiva" representó un cambio esencial en la mentalidad sobre la documentación. Sugirió que, en lugar de priorizar la documentación integral por adelantado, podríamos crear documentación valiosa a medida que desarrollamos el software. 

Parece que hoy hay un estigma sobre la documentación en Agile. ¿Qué opinas acerca de su papel en esta metodología? 

JG: Las afirmaciones del Manifiesto Agile tomaron la forma de "esto por sobre lo otro". No obstante, lamentablemente, a menudo se malinterpretaron como "esto sí, y lo otro no". Vemos eso con la documentación de forma frecuente. 

No queríamos decir que los equipos no deberían producir ninguna documentación. Simplemente, que no existe una receta única para ella. El Manifiesto Agile no dice nada sobre cómo abordarla porque no sabríamos qué decir. Las necesidades de cada equipo son diferentes. Sin embargo, no ofrecer directrices específicas sobre cómo crear documentación no significa que no la necesites. 

La documentación puede ser muy útil para lograr un entendimiento común entre los equipos y las partes interesadas. Por ejemplo, la documentación de diseño es necesaria para el mantenimiento del sistema, los revisores externos y los desarrolladores remotos. La clave es reconocer que las necesidades de documentación varían según factores como el tamaño del equipo, la distribución, las regulaciones o la industria.

Recomendaría a los equipos usar el Manifiesto Agile como un punto de partida para el diálogo y para establecer qué necesidades únicas deben satisfacer. Por ejemplo, un equipo pequeño y ubicado en el mismo sitio puede compartir información técnica, como la arquitectura, en persona o mediante una pizarra, pero un equipo grande que esté distribuido por todo el mundo necesitará determinar nuevas formas de comunicar esa información. 

Sabiendo que no hay una fórmula prescriptiva para la documentación, ¿qué consejo les darías hoy a los equipos ágiles sobre la documentación?

JG: Primero, recordar que cada documento que se crea debería tener valor. Antes de elaborar cualquier documentación en Agile, debe saberse para quién se está creando y para qué se usará. Eso ayuda a evitar esfuerzos desperdiciados y ahorra tiempo, porque se involucra a las personas adecuadas en su creación. 

Cuando se decide crear un documento, tener en cuenta estos consejos:

Usar imágenes para la alineación de alto nivel 

Las imágenes son una excelente manera de comenzar a explorar las ideas y hacer que las personas estén en sintonía. Empieza con una visión de alto nivel de hacia dónde te diriges. Puedes pensar en esto como un mapa. Cuando trabajes en algo desde cero, comienza con un documento que describa las bases, comunique las convenciones y los ayude a tu equipo y a ti a navegar por el sistema. 

Lo importante es saber cuándo parar. Usa estas imágenes para explorar la interacción entre los sistemas y crear alineación, pero sin exagerar. Puede haber muchos escenarios relacionados: documenta algunos para mostrar el patrón y alinear a las partes interesadas.

Crear documentación de forma iterativa

Empieza con una visión del producto. Es probable que sea algo vago y borroso. Documéntalo de la forma más sencilla que pueda funcionar; podría ser una lista de viñetas o bocetos en una pizarra virtual o real. A medida que el proyecto avanza, esta visión se vuelve más clara. Aprendes más sobre el problema que se está resolviendo y su posible solución.

Esta documentación está pensada para ser de alto nivel, así que trata de mantenerla así. Luego, puedes agregar más detalles en el propio código. Por ejemplo, en un diagrama de UML se mencionarían operaciones representativas, pero no se especificarían firmas de funciones detalladas. El mapa del sistema te ayuda a guiarte hacia los detalles, en lugar de dificultar tu visión con demasiada información.

También puedes adoptar un enfoque iterativo con código autodocumentado: código con estructura y sintaxis que explica claramente cómo funciona sin comentarios ni documentación adicional. Por ejemplo, en mi propio sitio web, he notado casos en que el código que escribí era difícil de entender. Parecía muy claro cuando lo creé, pero no lo era dos semanas después. ¡Parecía que alguien hubiera irrumpido y lo hubiera arruinado! Así que lo mejoro cambiando los nombres y la estructura. La próxima vez que visito el código, normalmente, está mejor explicado. 

Convertir el trabajo que ya se está haciendo en documentación

Antes de crear un documento, pregúntate: ¿hay alguna manera de crearlo que vaya mejor con lo que ya hacemos?

La documentación ejecutable puede capturar los detalles sin crear trabajo adicional. Te daré un ejemplo. Hace mucho tiempo, trabajé con una empresa que tenía un paso de proceso definido: documentar cómo ejecutar la prueba unitaria del código. Era un proceso manual que se volvió obsoleto con el tiempo.

En lugar de un proceso manual documentado, ¡usa las pruebas unitarias automatizadas! Eso significa que, en lugar de escribir un documento sobre cómo se comporta el código, escribes pruebas que se aseguran de que el código actúe de cierta manera. Cuando el código deja de seguir su especificación, una prueba falla. Con el desarrollo basado en pruebas, las pruebas y el código se mantienen sincronizados de forma natural. Además, volver a probar es, prácticamente, gratis.

Las pruebas se convierten en la documentación. Indican de forma inequívoca cómo debe funcionar el código, mientras que, si estuviera escrito en un lenguaje natural como el inglés, sería algo ambiguo y quedaría a libre interpretación.  Un documento puede quedar obsoleto, pero las pruebas siempre reflejan información actualizada sin crear trabajo adicional. El documento más barato es el que ni te molestas en escribir.