Hace un par de años heredamos un proyecto con un cliente donde casi no había documentación. Todo, cómo funcionaba, por qué se había hecho así, qué decisiones había detrás, vivía en la cabeza de los desarrolladores. Y mientras esas cabezas estén disponibles y se acuerden, funciona. El problema es que sabemos que ninguna de las dos cosas dura para siempre.
Terminamos parando casi dos meses, entre varios, solo para levantar la documentación de algo que ya estaba construido. Dos meses que no le facturas a nadie como "avance", esto fue puro costo, para nosotros y para el cliente, en vez de estar haciendo cosas nuevas. Todo por no haber escrito las cosas cuando estaban frescas.
Acá está la verdad incómoda: cualquier proyecto que no documentas se vuelve "solo en tu cabeza" con el tiempo, el conocimiento se pierde si no lo anclas a algo escrito.
La jugada: documentar sin que duela
Documentar siempre fue la tarea que nadie quiere hacer. La dejas para después, y después nunca llega. Eso cambió, y cambió de verdad, cuando la IA se metió en el proceso.
Nosotros trabajamos con dos cosas simples: especificaciones (qué queremos lograr y por qué) y ADRs — registros de decisión, que es una forma elegante de decir "por qué elegimos A y no B, y en qué momento". Nada sofisticado: documentos cortos, fáciles de leer.
Lo clave es cómo los escribo ahora. No parto de la hoja en blanco. Soy bien específico en el objetivo, levanto algunos casos borde, y dejo que la IA haga el primer borrador. De ahí vamos revisando juntos, empujando en los puntos más críticos hasta que quedo conforme, y recién ahí lo pasa el equipo para una revisión final. La IA hace el 80% pesado del texto; yo pongo el criterio en el 20% que importa.
Ese cambio es todo. Documentar dejó de ser dos horas de flojera pura y pasó a ser veinte minutos de revisar y afinar. Cuando la parte aburrida la hace otro, la excusa se cae sola.
El pago es doble (y esto es lo que no vi venir)
Lo obvio: el proyecto queda documentado, un desarrollador nuevo entra sin que yo le explique todo tres veces, y cuando el cliente pregunta "¿por qué hicieron A y no B?" tengo la respuesta escrita, no un "déjame acordarme".
Pero hay algo más grande. Esos documentos los lee la IA igual de bien que un humano. Eso significa que puedo llegar con cualquier modelo, pasarle las specs y los ADRs, y el modelo sabe en el momento en qué estamos y por qué. La documentación se volvió el contexto que le doy a la IA para que trabaje bien, justo lo que venimos hablando: el modelo rinde tanto como el contexto que le pones alrededor.
Y hay un beneficio que casi no se habla: evitas retrabajar. Muchas veces algo se ve "poco óptimo" a primera vista, pero en su momento se tomó una decisión técnica o de negocio con razón. Si está documentada, nadie la deshace por que no le parece. Y de paso dejas anotadas las mejoras a futuro, para cuando sí toque.
Cierre: entregarle al cliente algo bien documentado es un plus enorme, para los dos lados. Se nota profesionalismo, y te ahorra a ti el dolor de cabeza de mañana.
Cómo lo replicas
No necesitas ser desarrollador para esto — sirve para cualquier proceso o decisión de tu negocio:
Escribe la decisión, no solo el resultado. "Elegimos al proveedor X" no sirve dentro de seis meses. "Elegimos X en vez de Y porque necesitábamos entrega en 48h y Z no la daba" sí. El por qué es lo que se evapora.
Deja que la IA haga el primer borrador. Tú das el objetivo, los casos borde y el criterio. Ella arma el texto ordenado. Tú revisas lo crítico. Documentar deja de doler.
Guárdalo donde la IA también lo pueda leer. Un doc simple, en texto plano, nosotros usamos la carpeta de docs como estándar. Así te sirve a ti hoy, al que entre mañana, y a cualquier modelo que uses para trabajar sobre eso.
Hoy ya no hay excusa para no documentar. La parte fome la hace la IA. Lo único que pones tú es la decisión de hacerlo antes de que el proyecto se te meta entero en la cabeza y no salga más.
Lo que está pasando
Esta semana quedó claro que el acceso a los modelos más potentes puede llegar tarde o con condiciones según dónde estés: el preview de GPT-5.6 de OpenAI arrancó limitado a ~20 socios aprobados uno a uno por el gobierno de EE.UU. Una razón más para que tu conocimiento viva en documentación tuya, portable, y no encerrado en la cabeza de un solo modelo o un solo proveedor.