Qué hacer y qué no hacer en la documentación agile

A medida que los equipos han pasado de la cascada a formas ágiles de trabajar en las últimas dos décadas, se ha generado un estigma negativo en torno a la documentación. 

Muchos equipos han malinterpretado la declaración del Manifiesto Agile de "software que funcione por sobre documentación completa" como "sin documentación". Aunque es cierto que los enfoques tradicionales de la documentación son ineficientes, la eliminación total de la documentación puede ser perjudicial para los equipos que usan la metodología Agile, en especial a medida que el trabajo remoto e híbrido se vuelve más común. 

Suponte que estás tratando de construir una casa. No importa lo rápido, gradual y eficiente que seas: si nunca haces los trabajos de encofrado y cimentación, la casa no se mantendrá en pie durante mucho tiempo. Del mismo modo, la documentación proporciona a los equipos ágiles los cimientos necesarios para aprender, adaptarse, innovar y ofrecer valor a los clientes. Sin ella, no están en sintonía, son propensos al error y la falta de comunicación, son ineficientes y carecen del contexto necesario para tomar decisiones y adaptarse a los cambios del mercado. 

En otras palabras, aunque eliminar la documentación puede parecer una forma de aumentar la agilidad de manera transitoria, en realidad, eso disminuye significativamente la agilidad a largo plazo.

En lugar de deshacerse de la documentación por completo, los equipos se enfrentan a la oportunidad de hacer mejor la documentación. La solución no es volver a cómo se abordaba la documentación en los días de la cascada. Es necesario adoptar una documentación que sea orgánica, dinámica, adaptable y muy visual.

¿Qué aspecto tiene el enfoque agile respecto de la documentación?

Un enfoque ágil respecto de la documentación sigue muchos de los mismos principios que el propio Manifiesto Agile, es decir: debe ser iterativa, adaptable y colaborativa. El objetivo de una documentación agile eficaz debe ser:

• Compartir mejor el contexto entre equipos híbridos y eliminar los intercambios innecesarios
• Permitir que los equipos salgan al mercado más rápido mediante la creación de plantillas de procesos repetibles
• Crear una experiencia de incorporación eficiente para los nuevos empleados

Dada la creciente complejidad de los negocios (más software, más datos, un ritmo de cambio acelerado y la creciente adopción del trabajo distribuido), las organizaciones no pueden darse el lujo de dejar de lado la documentación; es una necesidad para trabajar con eficiencia e innovar continuamente.

Y a medida que las empresas se enfrentan a presupuestos cada vez más ajustados, a la rotación de personal y a otros obstáculos para su negocio, una mejor documentación ayuda a evitar que los conocimientos valiosos se escapen por la alcantarilla.

¿Cuáles son algunos ejemplos de documentación agile? 

La documentación agile implica documentos, diagramas o plantillas que son fáciles de entender, muy visuales y que ayudan a los equipos a tomar decisiones y avanzar. Eso puede incluir:

• Backlogs del producto
• Diagramas de quemado y de trabajo pendiente
• Mapas de historia de usuario
• Diagramas UML

Aunque estos son documentos importantes para mantener a los equipos en sintonía, también existen formas menos formales de documentar la información que son igualmente importantes para la innovación continua.

Por ejemplo, si organizas tus eventos ágiles de forma remota, usa una sala virtual de equipo para capturar ideas, obstáculos o comentarios. Ese espacio virtual actúa como una forma de documentación dinámica que proporciona un registro del contexto y las decisiones del proyecto.

Qué hacer y qué no hacer en la documentación agile

Con todo esto en mente, aquí hay algunos consejos tácticos para abordar tu práctica de documentación agile:

Sí: Documentar continuamente mientras trabajas

Gran parte de las quejas sobre la documentación tienen que ver con que es un proceso intensivo que le quita tiempo al trabajo real de codificación y desarrollo del producto. Sin embargo, no tiene por qué ser así.

Un artículo reciente de InfoQ postula un enfoque de documentación continua que se basa en acoplar tu documentación con la codificación y producir documentación "cuando sea mejor", que podría ser inmediatamente después de una corrección de errores, por ejemplo, en lugar de solo después de un gran proyecto. Y los propios escritos de Lucid sobre repositorios de innovación sugieren un enfoque para convertir todo el trabajo más amplio de lluvias de ideas, planificación y ejecución que ya se está haciendo en un "plan dinámico" de cómo tu negocio lleva a la práctica sus mejores ideas.

Pensar en la documentación de esta manera la convierte en una extensión natural del proceso de creación, codificación, seguridad, pruebas de venta y marketing, en lugar de ser una tarea separada que se hace a regañadientes. También es más eficiente documentar mientras se trabaja porque se pueden tomar notas del proceso sin que este deje de ser lo más importante.

No: Crear documentación porque sí

A lo largo del proceso de documentación continua, es importante hacerse las siguientes preguntas para evitar crear documentación sin sentido:

• ¿Cuál es el propósito de esta documentación?
• ¿Para quién es este documento y cómo lo usará? 
• ¿Este documento ya existe en otra parte?

Adoptar una mentalidad de documentación continua no significa que debas hacer trabajos redundantes, sino que debes buscar oportunidades para agregar documentación y mejorar la existente siempre que sea posible.

Abordar los problemas de gestión de versiones, optimizar una documentación difícil de encontrar o difícil de leer para facilitar la disponibilidad de la información y la legibilidad, o agregar capturas de pantalla y diagramas a la documentación con mucho texto son formas importantes en las que puedes cambiar la base de conocimientos de tu empresa más allá de crear nuevos documentos desde cero.

Sí: Buscar oportunidades para automatizar siempre que sea posible

Agregar base de datos y otras integraciones puede reducir los errores que surgen cuando tienes que actualizar la documentación manualmente, en especial los diagramas de entidad-relación (ERD, por sus siglas en inglés) u otra documentación que muestre relaciones de datos complejas. 

La automatización también puede ayudarte a ahorrar tiempo y trabajo manual, ya que se actualizan partes clave de tu documentación sin que ni siquiera lo pienses (o sepas que está ocurriendo). Tener los datos más recientes al alcance de la mano en lugar de tener que buscarlos puede ayudarte a generar información mejor y más útil y a descubrir patrones que, de otro modo, podrías haber pasado por alto.

No: Esperar hasta el final del proyecto para documentar

Esperar hasta que termine un proyecto para documentarlo conlleva el riesgo de olvidar información, introduce más espacio para el error y agrega una carga innecesaria al final de un sprint largo, cuando el entusiasmo por hacer "una cosa más" probablemente esté en su punto más bajo.

Si abordas la documentación agile desde la perspectiva de la creación de un repositorio de innovación en el momento y a lo largo del tiempo, la documentación se integra como una parte natural del proyecto (desde la idea y la planificación hasta el diseño y el lanzamiento) en lugar de ser una tarea añadida al final.

No: Producir documentos en silos

Dedicar tiempo a crear documentos individualmente y luego recopilar comentarios cuando ya empezaste un borrador es ineficiente. Si el alcance de tu documentación no es adecuado o faltan detalles críticos, tendrás que dedicarle tiempo a una revisión importante que es completamente evitable.

Involucrar a otras personas desde el principio mediante entrevistas de descubrimiento para averiguar qué documentación es realmente necesaria, o invitándolos a colaborar en la propia documentación, te ahorrará tiempo y dificultades más adelante.

Sí: Crear documentación en colaboración con el equipo

La documentación no tiene que ser un esfuerzo individual, especialmente cuando se crea a partir de código, tableros de lluvia de ideas, mapas de planificación u otros documentos que ya se han creado en equipo.

Involucrar a otros en el proceso asegura que el equipo tenga conocimiento y esté de acuerdo, lo que lo convierte en un proceso colaborativo. También crea la responsabilidad colectiva de asegurar que la organización sea rigurosa en cuanto a la documentación, lo que refuerza la importancia de mantener los documentos actualizados como equipo. Para los empleados más nuevos o júnior, participar en el proceso de creación también puede ser una experiencia de aprendizaje muy memorable.

Uno de los mayores puntos de dolor de la documentación es la frecuencia con la que debe actualizarse y la cantidad de trabajo de comunicación y distribución que debe hacerse para asegurarse de que todos estén al tanto de que hay una nueva versión disponible.

Utilizar una opción de almacenamiento basada en la nube, preferiblemente una que se adapte a la colaboración visual para que la información sea aún más comprensible, significa que no tendrás que lidiar con problemas de control de versiones y garantiza que los miembros del equipo tengan acceso a la información que necesitan para tomar decisiones de forma rápida y confiable.

No: Usar la documentación para reemplazar la conversación

Si bien la documentación visual clara puede permitir el trabajo asíncrono, debe complementar la conversación y no reemplazarla. Crear una mejor documentación no se trata de desentenderse de la necesidad de colaborar con los compañeros de equipo. Debe hacer que esas conexiones sean más fuertes y servir de fuente de información para conversaciones que conduzcan al pensamiento creativo y a la innovación.

Recuerda este principio de la metodología Agile: el método más eficiente y efectivo para transmitir información dentro de un equipo de desarrollo es la conversación cara a cara.

Sí: Usar elementos gráficos atractivos y simples

La documentación que prioriza los elementos visuales por encima del texto puro te ayuda a aclarar la información compleja y a mostrar relaciones entre entidades con mayor simplicidad, y es más fácil de entender de un vistazo para las partes interesadas.

Imagínate empezar en una nueva empresa y descubrir que su organigrama está escrito completamente como una lista con viñetas. No hay jerarquía, ni niveles, ni líneas que muestren las estructuras de reporte, solo una lista de nombres y cargos, y tú tienes que hacer todo el difícil trabajo de entender la relación entre las personas y los equipos.

Aunque es un ejemplo extremo, el mismo principio se aplica al uso de elementos visuales para cualquier tipo de documentación. Los elementos visuales claros le ahorran al lector la necesidad de esforzarse para comprender estructuras complejas, relaciones y dependencias, y le deja más tiempo para centrarse en las responsabilidades laborales reales.

No: Crear documentos demasiado densos y con mucho texto

En un intento de ser minucioso con la documentación y poner tus ideas en papel, puede ser difícil recordar que no necesariamente estás escribiendo la documentación para ti mismo. Si escribes para ti mismo y no para los demás, puedes tender a pasar por alto pasos importantes, no detectar faltas de información evidentes o esconder la información importante en un denso bloque de texto.

El problema es que a menudo terminas con un documento que puede tener sentido para ti (porque tienes experiencia y contexto sobre el proceso), pero que es incomprensible para alguien que intenta el proceso por primera vez.

Si ves que la documentación siempre tarda mucho tiempo en producirse, podría ser que te estés extendiendo demasiado. Si la documentación es tan densa que no es clara y no se utiliza, no es una buena documentación. Menos es mejor.