Extreme Programming presenta el principio de YAGNI (You Aren't Gonna Need It - No lo vas a necesitar), el cual nos advierte sobre no invertir tiempo sobre-construyendo sofware que seguramente no va a necesitar esa funcionalidad extra de todas formas, y que este tiempo podría usarse para construir cosas que si son necesarias. Existe un concepto complementario respecto a la documentación: TAGRI (They Aren't Gonna Read It - No lo van a leer).

Todo parte sabiendo que se termina leyendo muy poca de la documentación que se crea durante el desarrollo de software. Aceptando esto, debemos modelar/documentar con un propósito y crear documentación ágil que refleje las necesidades reales de la audiencia; la mejor forma de lograr esto es trabajar junto a la gente para quienes estamos escribiendo la documentación. Cuando hacemos esto podemos descubrir que pueden necesitar algo completamente diferente a lo que pensábamos originalmente.

El problema

Todos los que trabajaron en Sistemas por algunos años, y en particular cualquiera que haya trabajado en una organización grande, escucharon o vivieron experiencias en donde la documentación se escribió para luego ser ignorada por la audiencia de destino. Es muy  comun ver:

• proyectos con requerimientos detallados, y equipos que ignoran parte de la especificación porque creen conocerla mejor.
• documentos de arquitectura detallados creados por un arquitecto de proyecto, y equipos que desarrollo que siguen su propio enfoque de todas formas, incluso aunque la arquitectura original era buena.
• documentos de pruebas detallados, y proyectos que los descartan porque el equipo de desarrollo se queda sin tiempo.
• documentos varios que se crean para guardar en cajones una vez que pasan alguna revisión de documentación.

Y para ejemplificar, veamos algunos anécdotas.

1. El documento de requerimientos que nunca le llegó a los desarrolladores. En la primavera de 2005 tuve el placer de visitar India. Mientras estaba allí pasé el tiempo en varias organizaciones debatiendo sobre cómo implementar Ágil. En parte del viaje pasé algo de tiempo con una persona que trabajaba para una firma de outsourcing de Sistemas. Parte de su trabajo era tomar los enormes documentos de requerimientos que provenían de sus clientes, que usualmente tenían cientos de páginas de largo, y resumirlos a algo menos de diez páginas. Este era el resumen que se le entregaba al equipo de desarrollo, y no el documento detallado. Hacian esto porque descubrieron que no importaba qué tan bien escrito estuviera el documento, el problema era que el documento siempre contenia errores, era contradictorio y demasiado detallado. Y esto llevaba a que se desarrollora software que no se necesitaba. La experiencia demostró que el equipo hacía un mejor trabajo si se les entregaba un documento de resumen y luego tenían charlas regulares con el cliente, como ser conferencias diarias. Es decir, esta organización que era CMMI nivel 4 descubrió que una estretegia para incrementar la productividad de manera significativa era reducir la documentación, no incrementarla.
   
2. La arquitectura de software que no fue. Hace ya unos años trabajé en un programa muy grande que estaba formado por una colección de proyectos relacionados. Había un equipo de arquitectura en común para los programas, cuyo objetivo era brindar una visión técnica para todos los equipos de desarrollo. Este equipo hacia un buen trabajo, entregando muy buenos modelos que imprimian y mostraban públicamente. También estaba disponible para consultas por los equipos. Algunos equipos trabajaban con los arquitectos y tomaban ventaja de su ayuda; otros simplemente los ignoraban creyendo que no serviría de mucho, y otros activamente trabajaban en contra del esfuerzo. Dos equipos incluso invirtieron tiempo para crear sus propias arquitecturas que competían entre si; una que era sospechosamente similar a la arquitectura oficial (les llevó bastante tiempo admitir que su esfuerzo privado fue una pérdida de tiempo), la otra era muy diferente (la oficial estaba basada en J2EE, y el equipo quería ir a .NET y gastó mucho esfuerzo en discusiones políticas de su enfoque: eventualmente perdieron). Al final, aunque existía una arquitectura definida, realista y de calidad, que era apoyada por la gerencia y por el propio equipo de arquitectura, la mayoría de los desarrolladores se negaron a tomarse el tiempo para leer la documentación.
3. Documentar luego del hecho. Hace unos años trabajé para una organización que construía software bajo las regulaciones FDA 21-CRF-11. El tema es que hay que tener un proceso definido y documentación suficiente para demostrar que el equipo realmente seguía con el proceso. El FDA hace auditorias aleatorias, y si se falla con una auditoria las cosas pueden complicarse para la empresa a nivel de capitalización en el mercado. Esta empresa tenía un proceso de desarrollo pero no lo seguía estrictamente, en mayor parte porque el proceso no era muy bueno. Así, muchos equipos de proyectos se encontraban con que, luego de entregar el software a producción, tenían que gastar varias semanas o meses creando la documentación requerida para hacer parecer que habían seguido el proceso. Esta documentación no tenía nada que ver con el desarrollo del software real, y su único motivo era poder pasar una muy poco probable auditoria de la FDA. Más aún, el objetivo de las regulaciones no es promover la documentación, sino reducir la probabilidad de perder la vida debido a errores en el software; la documentación luego de haber terminado el desarrollo no cumplia con este objetivo.
4. El proceso de software que no se leía. Perdí la cuenta de la cantidad de organizaciones en las que alguien pensaba que era una buena idea escribir una descripción detallada del proceso de software, o mejor áun comprar un proceso y modificarlo. Aunque en general esta descripción del proceso es bastante buena, y las personas que lo escriben son muy entusiastas al respecto, los profesionales de Sistemas que tienen que seguir el proceso pocas veces se molestan en leerla. Las personas con experiencia pueden ojear la documentación, o simplemente esperar al día de capacitación; los nuevos leen la introducción y partes específicas durante la primera semana de trabajo. Pero invariablemente nadie lee el proceso durante el desarrollo de software, generalmente porque los profesionales de IT están muy capacitados y no necesitan leer los procedimientos antes de hacer el trabajo. En resumen, el esfuerzo de definición del proceso fue una pérdida de tiempo.

En varios proyectos de desarrollo de software se crean muchos documentos que no son necesarios, o en donde sólo pequeñas porciones de la documentación se necesita realmente. Todas estas anécdotas muestran problemas más produndos dentro del proceso de desarrollo, pero al adoptar el principio de TAGRI vamos a poder enfrentar algunos de los desafios.

La solución

Uno de los mitos sobre el desarrollo ágil es decir que no escribimos documentación. Nada podría ser más alejado de la verdad. En Ágil se escriben documentos de alto valor y efectivos y, eso si, en la práctica resulta ser menos documentación que la forma tradicional de escribir. Esto se logra siguiendo algunas pocas reglas:

• Tratar a la documentación como a cualquier otro requerimiento. Cualquier documento, incluso aunque sea relacionado con Sistemas, debe ser costeado, priorizado y tratado como cualquier otro requerimiento del sistema. Esto ayuda a identificar rápidamente la documentación que brinda valor, y todavía más importante ayuda a enfocar el esfuerzo para asegurarse que se crea la documentación que es necesaria.
  
• Crear documentos teniendo en claro quién es la audiencia. En Ágil creamos documentos con un propósito: sabemos para quién creamos la documentación, qué van a hacer con ella, y que esperan de la misma. Sin saber esto no se puede predecir lo que se necesita, y por lo tanto estaremos motivos a sobre-documentar. Por ejemplo, muchos equipos de desarrollo tradicional producen documentos completos del sistema, que se entregan al equipo que se encargará del mantenimiento. Sin embargo, en la práctica, muchos programadores de mantenimiento no confian en la documentación y a menudo lo ojean rápidamente para tener una idea de en dónde podría estar el problema, y luego se meten en el código para arreglarlo (o para agregar una característica nueva, depende del caso). Cuando se observa a los programadores de mantenimiento en la práctica, no suelen necesitar ni querer la mayoría de la documentación. La mayoría prefiere introducciones bien escritas y breves (quizás sólo unos cuantos diagramas y un resumen de las decisiones más importantes), una suite de pruebas de regresión, y código fuente de alta calidad. Entonces, ¿por qué no darles esto?
• Trabajar junto a la audiencia para identificar sus necesidades reales. La forma más facil que conozco para saber lo que alguien necesita de un documento es involucrarla en la creación del mismo.
• Escribir documentación ágil. Hay muchos motivos para documentar, algunos buenos y otros malos, y mi consejo es que cualquier documentación que escriban tiene que ser lo suficientemente buena para la situación actual. La documentación compleja y extravagante no va a ser leída, e incluso aunque lo sea van a estar gastante el tiempo del lector.
• Fuente única de información. Cuando se crea una fuente única de información se busca registrar todo en un único lugar. Ejemplos comunes de esta práctica son el uso de las pruebas de aceptación como requerimientos completos, y de pruebas unitarias como diseño detallado; las pruebas se convierten en especificaciones ejecutables. La única documentación que debería escribirse es para aquella información crítica que no puede ser capturada utilizando otros medios.

¿Cuándo crear un documento?

Para determinar si tiene sentido crear un documento, y si lo tiene qué tan lejos llegar, es bueno responderse estas preguntas:

• ¿Quién va a usar este documento?
• ¿Cómo lo van a usar?
• ¿Qué esperan que aparezca en el documento? ¿En qué formato?
• ¿Quién va a pagar por este documento?
• ¿Qué necesita decir realmente?
• ¿Cuál es la forma más consisa de decirlo?
• ¿Qué ocurrirá si el lector necesita más detalles?
• ¿Existe un documento que podamos referenciar de forma parcial o total?

Basado en The TAGRI (They Aren't Gonna Read It) principle of software development.