Por qué Confluence no funciona (y qué es lo que sí funciona)

Si has trabajado en ingeniería durante más de unos pocos años, habrás experimentado el ciclo de vida de Confluence. Un nuevo equipo o una nueva iniciativa crea un espacio en Confluence. Ingenieros motivados escriben la documentación inicial: descripciones generales de la arquitectura, documentos de diseño, guías de procesos. El espacio se ve genial durante las primeras semanas.

Luego se detiene el mantenimiento. Se envían PRs sin las correspondientes actualizaciones de la documentación. Los cambios en la arquitectura no se reflejan. Se incorporan nuevos ingenieros y descubren que los documentos describen un sistema que existía hace seis meses. Los ingenieros sénior advierten a las nuevas incorporaciones que "la wiki está mayormente desactualizada" y sugieren preguntar en lugar de leer. El espacio de Confluence se convierte en un cementerio de buenas intenciones: páginas bien estructuradas y con un formato agradable que describen una versión de la realidad que ya no existe.

Este no es un problema específico de Confluence. Es un problema de cualquier sistema de documentación que dependa de que los humanos escriban y mantengan los documentos manualmente. Las wikis de Notion se vuelven obsoletas de la misma manera. Google Docs acumula desviaciones de forma idéntica. Las páginas de GitBook se deterioran al mismo ritmo. La herramienta no es el problema. El modelo lo es.

Por qué falla la documentación manual

La documentación manual falla porque requiere que un humano realice un trabajo que no produce un valor directo y visible, y porque el esfuerzo es continuo en lugar de ser algo de una sola vez.

Escribir un documento es un coste único. Mantenerlo al día es un compromiso indefinido. Cada sprint, cada refactorización, cada cambio de arquitectura crea trabajo de mantenimiento de documentación, y ese trabajo nunca se prioriza porque no lanza funcionalidades, no corrige errores y no mueve las métricas que nadie está siguiendo.

El resultado es que incluso los equipos con una sólida cultura de documentación acumulan deuda de documentación de forma constante, porque la velocidad de cambio del sistema siempre supera la velocidad de mantenimiento de la documentación. Cuanto más rápido lanzas código, más rápido se desactualizan los documentos, y la paradoja de la documentación asegura que los equipos que más tienen que documentar son los menos capaces de mantener el ritmo.

El diseño específico de Confluence empeora esto de varias maneras. Su búsqueda es tan débil que los ingenieros a menudo no pueden encontrar los documentos incluso cuando existen. Su interfaz de edición desincentiva las actualizaciones rápidas porque el editor de páginas es muy pesado en comparación con escribir en un archivo de código. Y su organización depende de que alguien mantenga activamente la estructura del espacio, lo cual es otra carga de mantenimiento que nadie prioriza.

El cambio de modelo

La alternativa no es una mejor herramienta de wiki. Es un modelo diferente de cómo se crea la documentación.

In el modelo manual, un ingeniero hace un trabajo y luego escribe sobre ese trabajo en un sistema separado. La escritura es una segunda tarea además de la primera, separada en el tiempo, separada en el contexto y dependiente de la motivación del ingeniero para hacerla.

En el modelo de autoescritura, la documentación se genera a partir del propio trabajo. Las descripciones de las PR se convierten en documentación de cambios del sistema. Las conversaciones de Slack se convierten en registros de decisiones. Las discusiones de las reuniones se convierten en documentos de planificación y arquitectura. El ingeniero no escribe documentos. El sistema los escribe a partir del trabajo ya realizado por el ingeniero.

Este cambio es importante porque elimina los dos modos de fallo que acaban con la documentación manual: el problema de motivación (los ingenieros no quieren escribir documentos) y el problema de actualidad (los documentos se desactualizan porque el mantenimiento no se prioriza).

Cómo es una wiki de autoescritura

Una wiki de ingeniería de autoescritura es una base de conocimientos estructurada y con capacidad de búsqueda que se mantiene a sí misma a partir de fuentes conectadas.

La documentación del sistema se actualiza a medida que se fusionan las PR, reflejando el estado actual de cada sistema en lugar del estado de cuando alguien se acordó por última vez de actualizar la página de la wiki.

Los registros de decisiones se crean a partir de discusiones de Slack donde se debaten y resuelven las opciones de arquitectura, preservando el razonamiento junto con la decisión.

Los materiales de incorporación se mantienen actualizados porque se derivan de las mismas fuentes que describen el sistema actual, en lugar de ser una instantánea de la última vez que una nueva contratación impulsó a alguien a actualizarlos.

Los historiales de cambios se compilan a partir de PRs y conversaciones, proporcionando una línea de tiempo de cómo ha evolucionado cada sistema y por qué.

Cada afirmación en la documentación incluye un enlace a su fuente, lo que significa que los ingenieros pueden verificar cualquier cosa haciendo clic para ver la PR original, el mensaje o la transcripción de la reunión. Esta arquitectura de citas es lo que separa a los documentos de autoescritura del texto generado por IA: la documentación se basa en pruebas en lugar de inferencias.

La migración

Pasar de Confluence a una wiki de autoescritura no requiere migrar todo el contenido existente el primer día. El enfoque pragmático:

Conecta tus fuentes de ingeniería (GitHub, Slack, reuniones). Deja que el sistema comience a generar documentación a partir de la actividad actual. Utiliza la wiki de autoescritura para la nueva documentación a partir de ahora. Conserva el espacio existente de Confluence como un archivo heredado para referencia histórica y deja que muera de forma natural a medida que la wiki de autoescritura se convierta en la referencia principal del equipo.

En unas pocas semanas, la wiki de autoescritura contendrá documentación actual generada a partir de la actividad en vivo, mientras que el espacio de Confluence contendrá documentación histórica de relevancia decreciente. La transición ocurre orgánicamente porque los ingenieros se sienten atraídos por la fuente en la que confían, y la fuente que se mantiene actualizada automáticamente gana confianza más rápido que la que requiere mantenimiento manual.

Preguntas frecuentes

Hemos invertido mucho en nuestra configuración de Confluence. ¿Tenemos que abandonarla? No. La wiki de autoescritura se encarga de la nueva documentación a partir de ahora. Tu contenido actual de Confluence sigue siendo accesible como referencia histórica. Con el tiempo, los ingenieros recurrirán de forma natural a la fuente que esté más actualizada y sea más confiable, pero no hay necesidad de una migración forzada.

¿Es la calidad del resultado comparable a la de los documentos manuales bien escritos? Para la documentación fáctica (qué hace el sistema, cómo ha cambiado, qué se decidió), la calidad es comparable o mejor, porque el sistema automatizado captura de manera exhaustiva mientras que la documentación manual captura de manera selectiva. Para la documentación narrativa (filosofías de arquitectura, principios de diseño, cultura de equipo), la redacción humana sigue siendo superior. El mejor resultado es una cobertura automatizada de los documentos fácticos con documentos narrativos escritos por humanos superpuestos.

¿Cómo gestiona esto la información conflictiva? El sistema utiliza la actualidad y la autoridad de la fuente para resolver conflictos. Una PR fusionada ayer tiene prioridad sobre un mensaje de Slack de hace tres meses. Los conflictos se marcan para revisión humana cuando el sistema no puede resolverlos automáticamente.

Lecturas relacionadas: Explicación de los documentos de autoescritura, La paradoja de la documentación, Por qué los ingenieros odian escribir documentos. Páginas relacionadas: Documentos de autoescritura, Para equipos de ingeniería, Fabric vs Confluence.