Resumen ejecutivo.
La documentación en procesos ágiles debe ser cuestionada siempre por el valor verdadero que aporta al proceso.
- No hay justificación de documentar solo por documentar.
- La documentación escrita es la forma más ineficiente y cara de comunicarse.
- Cuesta dinero crear y mantener documentación y por lo mismo la decisión de que y cuanta hacer es una decisión que debe tomar el patrocinador del proyecto en base al valor que aporta.
- El tiempo que se usa creando y manteniendo documentación es tiempo que no se dedica al desarrollo de software.
- Crear código auto documentado y documentación viva (pruebas automatizadas) es mucho mejor que la documentación estatica.
- Los requerimientos del software se capturan de forma mucho más efectiva usando “User Stories”.
Recientemente recibí retro alimentación de una conferencia que tuve la oportunidad de ofrecer en el Tecnológico de Nogales; la inquietud de algunos alumnos participantes giraba alrededor del asunto que el desarrollo ágil de software la da más valor a la comunicación directa entre las personas que a la documentación escrita.
Es muy posible que se haya exagerado el punto de no producir documentación a favor de conversar y discutir, si así fue entonces debemos aclarar y abundar en el tema de la documentación y el papel que juega dentro del contexto de un desarrollo ágil de software...
Debemos empezar por el principio y el principio es el Manifiesto Ágil. En éste se establecen cuatro valores fundamentales y 12 principios. El segundo estatuto de valor determina que:
“Se valora más el software funcionando que la documentación extensiva”
Del mismo manifiesto obtenemos el principio #6 que dice:
“La forma más eficiente y efectiva de comunicar información de ida y vuelta dentro de un equipo de desarrollo es mediante la conversación cara a cara”
Wikipedia en su articulo del manifiesto tiene lo siguiente respecto del tema:
“Poder ver anticipadamente como se comportan las funcionalidades que se esperan sobre prototipos o sobre partes ya elaboradas del sistema final ofrece un "feedback" muy estimulante y enriquecedor que genera ideas y posibilidades imposibles de concebir en un primer momento, y difícilmente se podrían incluir al redactar un documento de requisitos detallados antes de comenzar el proyecto.
El manifiesto no afirma que no hagan falta. Los documentos son soporte de documentación, permiten la transferencia del conocimiento, registran información histórica, y en muchas cuestiones legales o normativas son obligatorios, pero se resalta que son menos importantes que los productos que funcionan. Menos trascendentales para aportar valor al producto.
Los documentos no pueden sustituir, ni pueden ofrecer la riqueza y generación de valor que se logra con la comunicación directa entre las personas y a través de la interacción con los prototipos. Por eso, siempre que sea posible debe preferirse, y reducir al mínimo indispensable el uso de documentación, que genera trabajo que no aporta un valor directo al producto.
Si la organización y los equipos se comunican a través de documentos, además de perder la riqueza que da la interacción con el producto, se acaba derivando a emplear a los documentos como barricadas entre departamentos o entre personas.”
De lo anterior podemos concluir entonces que aunque la documentación es importante para un proyecto de desarrollo, es más importante desarrollar y producir software que funciona y que funciona bien.
Mi experiencia personal de seguir al pie de la letra el paradigma tradicional de cascada, donde se escribe primero la documentación es que al final de muchos meses lo único que tienen los patrocinadores del proyecto es una pila de papel que no resuelve los problemas de negocios planteados. En un proyecto en el que actualmente partícipo, despues de producir documentos por mucho tiempo, adoptamos la agilidad y empezamos a entregar software funcionando; los documentos que habiamos producido con tanto esfuerzo ni siquiera fuerón consultados y nadie ya le interesan. De hecho, la evolución de la empresa y de los requerimientos los dejarón obsoletos.
Recuerdo muy especificamente una ocasión (de las muchas) en que tuvimos que justificar la tardanza en terminar el sistema; imprimí todos los documentos de diseño y todos los casos de uso como respaldo de nuestro trabajo de meses para presentarselos a los patrocinadores del proyecto. Les puedo decir que no nos sirvio de mucho. Sin embargo, cuando les mostramos un programa que ya funcionaba y estaba instalado no les importo en que habiamos estado “gastando” nuestro tiempo.
La experiencia colectiva de miles de equipos de desarrollo y los estudios que se han hecho demuestran que escribir tomos y más tomos de documentación siguiendo la metodología tradicional solo aumenta el riesgo de fracaso de esos proyectos.
Documentación ágil
- El asunto fundamental es la comunicación y no la documentación.
- Los agilistas escriben documentación si esa es la mejor manera de alcanzar los objetivos relevantes, pero frecuentemente se prueba que hay mejores caminos de alcanzar esas metas que escribir documentación estatica.
- Documentar solo cosas estables y no cosas especulativas.
- Darle un enfoque evolutivo al desarrollo de la documentación, buscando y luego actuando sobre la retro alimentación de forma regular.
- Se deben preferir productos ejecutables de trabajo tales como pruebas de cliente y de código automatizadas sobre artefactos estaticos tales como la documentación tradicional.
- Se debe entender el costo total de propiedad (TCO por sus siglas en ingles) de los documentos y alguién debe tomar la decisión explicita de hacer esa inversión.
- La documentación bien escrita promueve efectivamente la memoria organizacional, pero es una forma pobre de comunicarse durante un proyecto.
- La documentación debe ser concisa: Las generalidades y los mapas son generalmente preferidos sobre documentos detallados.
- Con código de alta calidad respaldado con un buen conjunto de pruebas automatizadas se requiere de menos documentación escrita.
- “Viajar lo más ligero” posible.
- La documentación debe ser apenas suficiente.
- La documentación comprensiva no garantiza el exito del proyecto, de hecho aumenta las posibilidades del fracaso.
- Los modelos no son necesariamente documentación y la documentación no es necesariamente modelos.
- La documentación es tanto parte del sistema como el código mismo.
- La meta principal del equipo de desarrollo es producir software, la meta secundaria es habilitar el siguiente esfuerzo.
- El beneficio de tener documentación debe ser mayor que el costo de crearla y mantenerla.
- Los programadores raramente confian en la documentación, particularmente aquella que es muy detallada porque usualmente no esta en sincronia con el código.
- Cada sistema tiene sus propias necesidades de documentación, un mismo tamaño no le queda a todos.
- Preguntarse si se NECESITA la documentación, no si se quiere.
- La inversión en documentación del sistema es una decisión de negocios, no es una decisión técnica.
- Crear documentos solo cuando se necesiten en el punto apropiado del ciclo de desarrollo.
- Actualizar la documentación solo cuando “duela”.
Como registrar los requerimientos del sistema
La definición, analísis y el registro de los requerimientos del sistema siempre ha sido terreno fertil para producir mucha documentación usando la cascada tradicional. El argumento siempre ha sido: Que mejor forma de registrar y comprometer lo que se quiere del sistema que la forma escrita y formal. Supuestamente, de esta forma, nadie puede decir así no era, así no les dije o eso no queria.
Sin embargo, no siempre lo más lógico y formal es lo mejor. En el caso de los requerimientos la mejor forma (a la fecha) de recuperar estos requerimientos es por medio de “User Stories”. Con este sencillo mecanismo, se documenta lo mínimo necesario, se postpone la discusión y el detalle de los requerimientos hasta el momento justo en que se empezará a desarrollar el software para satisfacer el requerimiento.
Una historia de usuario se escribe usando una o dos oraciones básicas cuyo propósito principal es servir de recordatorio del requerimiento para el momento de empezar a programar. Se recomienda el formato sugerido por Mike Cohn en su libro “User Stories Applied”: “Como <rol de usuario> quiero <funciónalidad> para <algún valor del negocio>”. Esto se registra en una simple tarjeta de cartoncillo. Este documento minimalista se usa para crear la pila de funciones, priorizarla y para planear las iteraciones.
Los documentos, modelos y diagramas durante el desarrollo
Durante el trabajo de escribir código se ocupan para apoyar ese trabajo diversos documentos, modelos y diagramas. Estos se deben crear justo a tiempo y solo con la formalidad necesaria para ilustrar y fácilitar la colaboración. Frecuentemente estos modelos se pueden hacer sobre una pizarra como apoyo a la discusión y descartarse una vez que los programadores han producido el código correspondiente.
Se recomienda no crear documentos formales para cosas que aún no estan estables, es decir, código que aún va a ser objeto de refactorado y mejora; lo mismo aplica para el modelo de bases de datos mientras esta en desarrollo.
Si la documentación tiene valor, debe ser creada solo sobre cosas que ya estan estables.
La documentación del usuario/operador
Se puede pensar que el 100% de los sistemas deben contar con un manual de usuario, sin embargo y con toda sinceridad, ¿cuantas veces se consulta el manual?. Entonces vemos como el manual del operador agrega poco valor al sistema. Un sistema que haya sido creado con la colaboración directa de los usuarios, rara vez ocupará un manual extenso para usarlo porque el sistema refleja las formas y los procesos de negocios. Antes, se ocupaba un manual porque el sistema determinaba los procesos de negocios, sin embargo hemos descubierto que no debe ser así. Los procesos de negocios deben evolucionar durante el desarrollo del sistema pero por iniciativa del valor hacia el negocio.
Ciertamente hay sistemas cuyo contexto operacional obliga el manual (el sistema de control de una planta nuclear más vale que tenga un buen manual), en esos casos esta claro el valor de negocios del manual y el beneficio de contar con este es superior al costo de crearlo y mantenerlo.
El principal problema del manual del operador es que para la gran mayoria de los sistemas, este manual se crea y rara vez se actualiza junto con la evolución del sistema.
Existen en la actualidad una alternativa muy atractiva para la creación y mantenimiento del manual del usuario: usar un wiki y que sean los mismos usuarios quienes crean y mantienen el manual.
Un wiki es un sistema que permite la creación y edición de páginas web de manera muy fácil y rápida. Contando con una herramienta como esta de bajo costo y de alta disponibilidad, durante el desarrollo podemos incluir a cada función del sistema una liga a una página aún no existente en el wiki.
Cuando se descubre que se ocupa documentación de esa función, el equipo de desarrollo colaborando con el cliente y los operadores pueden producir la documentación necesaria justo a tiempo y está puede evolucionar cuando sea necesario. De ésta forma, el manual de operaciones del sistema se crea y se mantiene solo cuando es necesario y por las personas en la mejor posición de hacerlo.
La documentación de sistema (la del mantenimiento)
Scott W. Ambler establece que la meta principal de los desarrolladores es producir software y que la meta secundaria es habilitar el siguiente esfuerzo. El siguiente esfuerzo se refiere al trabajo de mantenimiento y evolución del sistema.
Efectivamente, el equipo que está en mejor posición de desarrollar la documentación necesaria para el mantenimiento es el que desarrollo el software en primer lugar. Sin embargo, la documentación escrita es la peor forma de transmitir información. Los desarrolladres deben usar mecanismos alternos para documentar la construcción del sistema:
- Pruebas de cliente automatizadas
- Pruebas de código automatizadas (TDD)
- Código de buena calidad auto documentado
- Diseño simple y funcional
(Lo anterior aplicado también a la base de datos.)
El momento para producir la documentación que se ocupa para fácilitar y hábilitar el siguiente esfuerzo es cuando se han estabilizado los artefactos (código, bases de datos, interfaces, etc.). Esto tipicamente sucede 2 o 3 iteraciones despues de haber producido el código correspondente.
El costo de desarrollar documentación
Estamos de acuerdo que las personas que estan la mejor posición de escribir documentación de sistema son las que escriben el código; así entonces si se quiere la mejor documentación la tienen que producir las gentes que producen el código. Sin embargo, cada unidad de tiempo que se dedique a los programadores a desarrollar documentación es una unidad de tiempo que no se dedico al desarrollo de software. Así entonces, la creación de documentos debe valorarse y priorizarse de la misma forma que los requerimientos del sistema.
El beneficio (valor) de la documentación debe estar por encima del costo de desarrollarla y mantenerla para que haga sentido de negocios integrarla al esfuerzo que se requiere del equipo de desarrollo.
Los patrocinadores del proyecto deben entender el Costo Total de Propiedad (CTP) de un documento. La documentación cuesta crearla y mantenerla, cuesta guardarla y protejarla y finalmente cuesta consultarla y estudiarla. Si el CTP es mayor que el beneficio de tenerla entonces no hace sentido de negocios desarrollar esa documentación, más cuando existen mecanismos alternos para comunicar información (código de buena calidad, desarrollo de pruebas automatizadas, entre otros).
