🤷 Entonces, ¿seguimos documentando?
Si aún sigues aquí tras la lectura de las anteriores entradas, es probable que ya tengas claro que mi respuesta es un rotundo sí. Pero, como en casi todo lo relacionado con nuestra industria, hay un matiz importante: el escenario ha cambiado; un mundo nuevo para unos, aunque no lo suficiente para otros.
En los últimos tiempos hemos vivido una explosión de herramientas que prometen hacernos la vida más fácil, pero la realidad es que la complejidad de nuestros sistemas también ha crecido a un ritmo igual de demencial. Microservicios, arquitecturas distribuidas, infraestructura como código, etc. La carga cognitiva necesaria para entender un proyecto moderno es mucho mayor que hace años.
Estamos en un punto de inflexión. Ya no documentamos solo para cumplir un expediente o para que un manager se quede tranquilo. Documentamos para no perder la cordura; para que la siguiente gota que colmará el vaso no acabe por resquebrajarlo. En un mundo donde la IA puede generar código a una velocidad superior a la del ser humano, el valor diferencial vuelve a recaer en las interacciones humanas y en la capacidad de compartir el contexto, ese “por qué” que ninguna máquina puede explicar con precisión (todavía, 2026).
👨🏽🍼 He nacido para esto
No podemos ignorar al elefante en la habitación. Las herramientas de IA Generativa han llegado para quedarse y, si soy sincero, tienen una capacidad casi “mágica” (la IA no es magia, de eso hablaremos otro día) para resumir textos infumables, explicarnos conceptos poco claros o generarnos analogías divertidas para entender problemas complejos.
Sin embargo, hay una trampa peligrosa en la comodidad y, si me lo permitís, en la pereza. Si delegamos todas las tareas de gestión del conocimiento y documentación a la IA, corremos el riesgo de perder el contexto de nuestro propio trabajo.
Escribir documentación no es solo teclear; es un proceso de ordenación mental. Yo llevo toda la vida haciendo listas para todo, completando cuadernos y cuadernos con garabatos y esquemas a mano alzada para poder decantar esa información en mi cerebro. La edad no perdona.
Cuando explicas cómo funciona un módulo, estás validando tu propio entendimiento sobre la solución (hola, Wittgenstein 👋). Si le pides a un LLM que documente tu código sin revisarlo, te conviertes en un cuidador de una caja negra que alguien ha construido por ti en base a quién sabe qué fuentes. Aprendamos a usar la herramienta para potenciar nuestra capacidad, no para atrofiar nuestra competencia técnica.
🧮 Estrategias para hoy (y para mañana)
Para cerrar esta serie, no quería irme sin dejar una lista de consejos prácticos. No son balas de plata, pero son las estrategias que me han funcionado para mantener la documentación viva:
Usar la IA con cordura: Utilízala para eliminar la tarea tediosa, no el razonamiento. Generar una plantilla base o resumir un acta de reunión es fantástico. Pero, por favor, evita esas Pull Requests con descripciones kilométricas autogeneradas que nadie se lee. Aporta tu toque humano, explica las decisiones difíciles y deja que la IA se encargue del formato.
Maximizar la interacción humana: La documentación más importante a veces no está escrita, sino hablada. Fomenta el pair o mob programming y las sesiones de arquitectura. En estas ceremonias es donde se transmite la cultura del equipo y las sutilezas del negocio.
Documentación colaborativa: Hoy en día sobran herramientas (Notion, Obsidian, Confluence, etc.), pero falta cierto criterio y muchas reglas. Necesitas (necesitamos) una estrategia clara y una estructura común. ¿Te imaginas un diccionario que no estuviese ordenado alfabéticamente? Pues así son muchas wikis corporativas. Define una taxonomía básica, un lugar para cada cosa, y sé implacable borrando o archivando lo que ya no sirve. La información obsoleta es ruido.
ADR (Architecture Decision Records): Lo mencioné en el post anterior y aquí está. Documenta las decisiones arquitectónicas importantes (qué base de datos usamos, por qué elegimos esta estructura de directorios, por qué descartamos aquella librería, cuál es el flujo de información antiguo y cuál el nuevo) en ficheros simples junto al código o en tu wiki corporativa. Es la mejor manera de viajar en el tiempo y explicarle a tu “yo” del futuro por qué hiciste lo que hiciste sin necesidad de una máquina del tiempo. Y no solo eso, es una manera de vender tu propia experiencia y logros ante procesos de promoción interna.
➕ En resumen
Ha sido un viaje interesante a través de estas tres entradas. Empezamos reconociendo que documentar nos da pereza y tiene mala fama, continuamos desmontando los mitos del Manifiesto Ágil y el Clean Code que nos sirvieron de excusa para dejar de escribir buena documentación y terminamos hoy asumiendo que, en la era de la IA, el contexto humano es más valioso que nunca.
La documentación no es un entregable final; es un acto de respeto hacia tus compañeros y hacia ti mismo. No busques la perfección, busca la utilidad. Y sobre todo, no dejes nunca que la herramienta sustituya a tu criterio como profesional.
El día que no necesitemos la documentación probablemente sea el momento en el que dejaremos de ser imprescindibles en esta industria.
En estos tres artículos en realidad he hablado de las propias limitaciones del ser humano y cómo esos límites conforman y conformarán nuestras actuales y futuras ideas. La documentación es un ancla de lo que sabemos y lo que supimos y siempre nos ayudará a saber hacia dónde se debe orientar nuestro siguiente paso.
🗂️ Otras entradas
🤖 ¿IA?
En este post se han utilizado herramientas de IA generativa para la corrección de estilo y de problemas gramaticales y/u ortográficos.