Casi nadie disfruta escribiendo documentación, y casi todo el mundo ha sufrido su ausencia. La experiencia típica tiene dos caras: el día que llegas a un proyecto sin documentar y tardas una semana en conseguir que arranque, y el día que tú mismo vuelves a un proyecto propio tras seis meses y no recuerdas por qué hiciste las cosas así.
La salida no es documentarlo todo, que es la forma más segura de acabar con documentos desactualizados que nadie lee. Es escribir poco, y escribir exactamente lo que alguien va a necesitar y hoy solo sabe una persona.
El problema de documentar demasiado
La documentación exhaustiva tiene un defecto que la condena: se desactualiza a la velocidad del código, y una documentación desactualizada es peor que ninguna.
Sin documentación, quien llega sabe que tiene que preguntar o leer el código. Con documentación incorrecta, sigue las instrucciones, falla, y pierde tiempo antes de darse cuenta de que el problema era el documento.
Por eso el criterio no es la cantidad sino la vida útil. Un documento que describe qué hace cada función envejece con cada cambio. Uno que explica por qué se eligió una base de datos sigue siendo válido años después, aunque el código cambie por completo.
La regla práctica que se deriva es sencilla: documentar lo que no se puede leer en el código. El qué y el cómo ya están ahí; el porqué, el contexto y las decisiones descartadas, no.
Los cuatro documentos que sí compensan
Cada uno tiene un lector concreto y una pregunta concreta, y esa es la razón de que se mantengan: cuando alguien necesita la respuesta y el documento está desactualizado, lo corrige, porque es la única fuente.
El README: arrancar en diez minutos
La prueba de un buen README es brutal y fácil de aplicar: una persona que no conoce el proyecto, con una máquina limpia, debería tener la aplicación funcionando en local en diez minutos siguiendo solo ese archivo.
# Nombre del proyecto
Una frase: qué hace y para quién.
## Requisitos
- Node 22 (ver .nvmrc), PostgreSQL 16, Docker
## Arrancar en local
cp .env.example .env # rellenar DB_URL y APP_KEY
docker compose up -d db
npm ci && npm run migrate
npm run dev # http://localhost:3000
## Pruebas
npm test
## Desplegar
Ver docs/operacion.md
## Dónde está cada cosa
- src/api endpoints
- src/dominio reglas de negocio
- migraciones/ cambios de esquema en ordenLo que no va en el README es la historia del proyecto, la explicación de cada decisión o una guía de estilo de veinte secciones. Todo eso tiene su sitio, y meterlo aquí esconde lo único que el README debe hacer bien.
La forma de mantenerlo vivo es aplicar la prueba de los diez minutos cada vez que alguien nuevo llega, y pedirle que corrija lo que no funcionó en el propio cambio. Esa persona es la única que ve los huecos, porque los demás ya los saltan sin darse cuenta.
Registrar las decisiones, no solo el resultado
El documento con más valor a largo plazo es también el más raro: un registro breve de las decisiones de arquitectura, con su contexto y las alternativas descartadas.
El código muestra que se usa cierta base de datos. No muestra que se evaluaron otras dos, por qué se descartaron y qué condición haría cambiar de opinión. Sin ese registro, dentro de un año alguien propondrá el cambio sin conocer los motivos, y o se repite una discusión ya tenida o se deshace una buena decisión por desconocimiento.
# 0007. Usar PostgreSQL en lugar de MongoDB
Fecha: 2026-03-12
Estado: aceptada
## Contexto
Los pedidos se relacionan con clientes, productos y facturas, y
necesitamos informes que crucen esos datos.
## Decisión
Usamos PostgreSQL. Los atributos variables de producto van en una
columna jsonb.
## Alternativas descartadas
- MongoDB: cruzar pedidos y facturas exigiría hacerlo en código.
## Consecuencias
Una sola base que respaldar. Si algún día el catálogo necesita
búsqueda por significado, valorar pgvector antes que otro motor.Cada decisión en un archivo numerado dentro del repositorio, junto al código. Nunca se editan después de aceptarse: si la decisión cambia, se escribe una nueva que la sustituye y se enlazan. Así el historial de por qué el sistema es como es queda completo.
El documento de operación: para las tres de la mañana
Hay un lector que tiene muy poca paciencia y mucha prisa: quien está atendiendo un incidente. Para esa persona sirve un documento distinto a todos los demás.
No explica cómo funciona el sistema. Enumera los problemas que ya han ocurrido o que previsiblemente van a ocurrir, y para cada uno, cómo se reconoce y qué se hace, con los comandos exactos listos para copiar.
## La cola de tareas deja de vaciarse
Síntoma: alerta "tareas pendientes > 500" o correos que no salen.
Comprobar:
psql -c "SELECT estado, count(*) FROM tareas GROUP BY estado;"
systemctl status app-trabajador
Si el trabajador está caído:
sudo systemctl restart app-trabajador
Si hay tareas atascadas "en_curso" hace más de 15 min:
psql -c "UPDATE tareas SET estado='pendiente'
WHERE estado='en_curso' AND ejecutar_en < now()-interval '15 min';"
Escalar a: persona responsable, si no se vacía en 10 minutos.La regla que lo mantiene útil es escribir o actualizar una entrada después de cada incidente, mientras el recuerdo está fresco. Cada problema resuelto deja la receta para la siguiente vez, y con el tiempo el documento cubre la mayoría de las situaciones reales.
Los contratos, generados y no escritos
La documentación de una API es el caso donde mejor funciona no escribirla a mano: generarla a partir del propio código o de una especificación que el código cumple.
Una descripción formal de la API, en el formato estándar abierto, sirve a la vez como documentación legible, como fuente para generar clientes y como contrato que se puede verificar automáticamente. Y como se genera o se comprueba contra el código, no se desactualiza sin que alguien se entere.
# Validar que la especificación es correcta
npx @redocly/cli lint openapi.yaml
# Generar documentación HTML legible a partir de ella
npx @redocly/cli build-docs openapi.yaml -o docs/api.html
# Comprobar en la integración continua que el servidor sigue cumpliéndola
npx dredd openapi.yaml http://localhost:8080El paso que convierte esto en algo fiable es el último: si la especificación y el servidor dejan de coincidir, la integración falla. Sin esa comprobación, la especificación acaba siendo un documento más que envejece.
Comentarios en el código: el porqué, no el qué
La documentación que vive dentro del código sigue la misma regla que el resto, y la mayoría de los comentarios la incumplen.
Un comentario que repite lo que hace la línea siguiente no aporta nada y se desactualiza en cuanto la línea cambia. Un comentario que explica por qué el código es así, y sobre todo por qué no es de la forma obvia, evita que alguien lo cambie a la forma obvia y reintroduzca un problema.
// Mal: repite el código
// incrementa el contador
contador++;
// Bien: explica lo que el código no puede decir
// El proveedor devuelve 200 con cuerpo vacío cuando se supera su cuota,
// en lugar de 429. Por eso comprobamos el cuerpo y no solo el estado.
if (res.status === 200 && !res.body) throw new CuotaAgotada();Los mejores comentarios suelen explicar una limitación externa, una decisión contraintuitiva o el enlace a la incidencia que motivó el código. Todo eso es invisible leyendo solo la implementación.
Dónde vive la documentación
La decisión de dónde guardarla parece menor y determina si se mantiene.
La documentación que vive en el mismo repositorio que el código tiene una ventaja decisiva: se cambia en el mismo cambio que el código. Quien modifica un comportamiento puede actualizar su documentación en el mismo envío, y quien revisa ve ambas cosas juntas.
La documentación que vive en otra herramienta, una wiki o un gestor de documentos, se desactualiza por una razón puramente mecánica: actualizarla exige recordar ir a otro sitio, y nadie lo recuerda con prisa.
Por eso la recomendación es tener en el repositorio todo lo técnico, en archivos de texto sencillo, y reservar las herramientas externas para lo que no cambia con el código.
Cómo empezar sin que dé pereza
Para un proyecto que hoy no tiene nada, intentar escribirlo todo de golpe es la forma más rápida de abandonar. Hay un orden que funciona.
- Primero el README, con la prueba de los diez minutos. Es el que más tiempo ahorra y el más corto.
- Después, una decisión por semana: cada vez que se tome una decisión técnica relevante, se escribe su registro. No hace falta reconstruir las antiguas.
- El documento de operación crece con los incidentes: una entrada tras cada problema resuelto.
- Los contratos se generan cuando aparezca el primer consumidor externo de la API.
Así la documentación crece al ritmo en que se necesita, y cada pieza existe porque respondió una pregunta real, que es la mejor garantía de que alguien la mantendrá.
Qué se le escapa a una IA con esto
La documentación es una de las tareas donde un asistente parece más útil y donde más fácil es producir algo inservible: documentos largos, bien formateados, que describen qué hace cada función y repiten el código en prosa.
Ese tipo de documento tiene justamente el defecto de fondo, se desactualiza con cada cambio, y encima es tan largo que nadie lo lee. El asistente no puede escribir el porqué de las decisiones, porque no estuvo en la conversación donde se tomaron.
La forma de aprovecharlo bien es darle ese contexto y pedirle la estructura: explicar la decisión y sus alternativas y pedir el registro en el formato breve, o describir un incidente y pedir la entrada del documento de operación con los comandos.
Y conviene aplicar siempre la misma prueba al resultado: si este documento se desactualizara, ¿alguien se daría cuenta y lo corregiría? Si la respuesta es que no, probablemente sobra.