¿Y si tus documentos se escribieran solos?

La documentación que se escribe sola suena como una contradicción. Se supone que documentar es una actividad humana: un ingeniero comprende algo, se sienta y lo explica con sus propias palabras. La idea de que la documentación pueda escribirse sola sugiere que la calidad sería terrible (contenido basura generado por IA) o que sería demasiado superficial para ser útil (archivos README generados automáticamente que nadie lee).

Ninguna de las dos cosas es lo que significa realmente en la práctica la documentación que se escribe sola.

Cómo funciona realmente

La premisa es que el conocimiento necesario para una buena documentación de ingeniería ya existe. Existe en las descripciones de las PR (Pull Requests), donde los ingenieros explican qué han cambiado y por qué. En las conversaciones de Slack, donde los equipos debaten decisiones de arquitectura, discuten pros y contras y resuelven dudas de diseño. En las grabaciones de reuniones, donde se establecen prioridades, se planifican migraciones y se revisan incidencias. En los mensajes de commit, en los documentos de diseño y en los comentarios de las revisiones de código.

Actualmente, este conocimiento es efímero. El hilo de Slack desaparece de la pantalla en cuestión de días. La PR se fusiona y se olvida. La grabación de la reunión se queda en una carpeta que nadie vuelve a abrir. El conocimiento se creó, se compartió y se perdió, todo en el transcurso de una semana laboral normal.

La documentación que se escribe sola captura este conocimiento a medida que se genera y lo estructura en una wiki persistente y con capacidad de búsqueda que se mantiene al día a medida que cambia la actividad subyacente.

El proceso funciona de la siguiente manera:

Conecta tus fuentes. Repositorios de GitHub, canales de Slack, grabaciones de reuniones, servidores de Discord. Estos son los lugares donde ya se está compartiendo el conocimiento de ingeniería.

El sistema lee y sintetiza. A medida que se fusionan nuevas PR, se producen nuevas conversaciones y se graban nuevas reuniones, el sistema procesa el contenido, extrae el conocimiento relevante para la ingeniería y lo integra en una documentación estructurada.

La wiki se mantiene sola. Cuando una PR cambia el funcionamiento de un sistema, la documentación sobre ese sistema se actualiza. Cuando una conversación de Slack resuelve una duda de diseño, los documentos correspondientes incorporan la decisión. La documentación se mantiene al día porque se deriva de la misma actividad que modifica los sistemas subyacentes.

Los ingenieros revisan y perfeccionan. El sistema genera el primer borrador. Los ingenieros lo revisan, corrigen imprecisiones, añaden contexto y enriquecen la documentación con detalles que el sistema automatizado no podría deducir. El papel del ingeniero pasa de ser autor a editor, lo que supone una tarea de diez minutos en lugar de una sesión de escritura de dos horas.

Qué aspecto tiene el resultado

La documentación generada está estructurada, incluye citas y es editable.

Estructurada significa que sigue un formato coherente: descripciones generales del sistema, documentación de API, registros de decisiones, historiales de cambios, wikis específicas de cada equipo. El formato está estandarizado, lo que significa que la documentación es fácil de navegar y predecible, independientemente del sistema que describa.

Con citas significa que cada afirmación en la documentación incluye un enlace a su fuente: la PR, el mensaje de Slack, la marca de tiempo de la reunión. Un ingeniero que esté leyendo la documentación puede hacer clic para ver el contexto original, verificar cualquier afirmación u obtener más detalles. Esto es lo que diferencia la documentación que se escribe sola del texto generado por IA: la documentación se basa en actividad real, no se genera a partir de los datos de entrenamiento de un modelo.

Editable significa que los documentos generados son un punto de partida, no un producto final. Los ingenieros pueden modificar, reestructurar y anotar los documentos. El sistema aprende de estas modificaciones, mejorando la generación futura.

Lo que no es

La documentación que se escribe sola no es texto generado por IA al que se le ha pedido que "escriba la documentación de nuestra base de código". Ese enfoque produce una prosa genérica y a menudo inexacta que parece un modelo de lenguaje adivinando lo que su sistema podría hacer.

La documentación que se escribe sola se genera a partir de tu actividad de ingeniería real: PR reales, conversaciones reales, reuniones reales. El resultado describe lo que realmente ocurrió, en lugar de lo que un modelo cree que podría haber ocurrido. Las citas ofrecen verificabilidad. La actualización continua garantiza la vigencia. La revisión humana aporta la garantía de calidad.

La distinción es importante porque la confianza en la documentación es frágil. Los ingenieros que descubran que los documentos generados automáticamente son inexactos dejarán de leerlos tan rápido como dejan de leer los documentos escritos manualmente que se han quedado obsoletos. La documentación que se escribe sola se gana la confianza al ser verificable (cada afirmación tiene una fuente) y estar al día (los documentos se actualizan a medida que cambia el sistema).

Las fuentes

La documentación que se escribe sola puede nutrirse de múltiples tipos de fuentes, y la cobertura mejora a medida que se conectan más fuentes:

GitHub: descripciones de PR, mensajes de commit, comentarios de revisión de código, debates sobre incidencias. Estos elementos capturan qué cambió y por qué.

Slack: debates sobre diseño, debates sobre arquitectura, hilos de respuesta a incidencias, conversaciones sobre toma de decisiones. Estos elementos capturan el razonamiento que no llega al código.

Reuniones: planificación de sprints, revisiones de arquitectura, análisis posteriores a incidencias, sesiones de incorporación. Estos elementos capturan el contexto verbal que normalmente se pierde.

Canales de ingeniería: canales de Slack dedicados a ingeniería, servidores de Discord u otras herramientas de comunicación donde se mantengan debates técnicos.

Cuantas más fuentes se conecten, más completa será la documentación y menos probable será que los conocimientos fundamentales se pierdan entre las herramientas.

Preguntas frecuentes

¿Qué tan precisos son los documentos generados? La precisión varía según la calidad de la fuente. Las descripciones de PR con explicaciones claras producen mejores documentos que los mensajes de commit de una sola línea. Las discusiones detalladas en Slack producen mejores documentos que los intercambios breves. El sistema de citas permite a los ingenieros verificar cualquier afirmación consultando la fuente original, y el paso de revisión detecta las imprecisiones antes de que se den por válidas.

¿Cuánto tiempo de ingeniería requiere la configuración? Conectar las fuentes suele llevar menos de una hora. El sistema empieza a generar documentación en cuanto se conectan las fuentes. El tiempo de revisión continuo es de aproximadamente diez a quince minutos semanales por ingeniero, frente a las cinco horas semanales que suele consumir la documentación manual.

¿Podemos controlar lo que captura el sistema? Sí. Tú eliges de qué repositorios, de qué canales de Slack y de qué categorías de reuniones lee el sistema. Se pueden excluir los canales privados, los repositorios sensibles y las reuniones confidenciales.

¿Reemplaza esto a Confluence/Notion/nuestra wiki actual? Puede reemplazarlos o complementarlos. El sistema de documentación que se escribe sola genera documentación estructurada y con opción de búsqueda que cumple la misma función que una wiki manual, con la ventaja de que se mantiene actualizada automáticamente. El contenido de la wiki existente puede conservarse junto a los documentos generados.

Lecturas relacionadas: Por qué es importante la documentación de ingeniería, La paradoja de la documentación, Por qué los ingenieros odian escribir documentación, La documentación que se escribe sola frente a Confluence. Páginas relacionadas: Documentación que se escribe sola, Para equipos de ingeniería.