Hablar de documentación en un proyecto de software es como hablar de hacer ejercicio: todo el mundo está de acuerdo en que es importante… pero muy poca gente lo hace con constancia.
¿Te suena esta escena?
“¿Quién sabe cómo se configura esto?”
“Puf… creo que lo hizo alguien que ya no está.”
“¿Y no está documentado?”
“Creo que había un README por ahí… pero está desactualizado.”
No estamos hablando de escribir manuales eternos ni de redactar tesis.
Se trata de dejarle pistas al “yo del futuro” (o al pobre que herede tu código).
Una documentación buena no es la más larga. Es la más útil.
¿Para qué documentamos?
- Para facilitar el onboarding de quien entra al proyecto.
- Para no tener que recordar todo de memoria: para usar el cerebro para pensar y no para recordar.
- Para entender decisiones pasadas, no repetir errores y conocer el contexto de las decisiones
- Para que el conocimiento no se quede en la cabeza de alguien: así evitaremos bus factor, interrumpir varias veces por el mismo tema a la misma persona.
En resumen: no todo es código, clean architecture y demás, tenemos que escribir código legible y documentación que nos ayude y de contexto para que nos cueste menos mantener el código.
Leer más: Documentar bien no es escribir mucho, es escribir lo justo (y en el sitio correcto)Principios clave de una buena documentación
Estos cuatro principios nos ayudan a decidir qué, dónde y cómo documentar:
- 🗺️ Proximidad: la documentación tiene que vivir cerca de donde se necesita. Si estás documentando cómo hacer el setup, que esté en el propio proyecto, no en un Notion escondido.
- 🔄 Evolución: si el código cambia, la documentación asociada también. Si no se mantiene viva, se convierte en ruido.
- 🔍 Haz explícito lo implícito: el código muestra el qué y el cómo, pero no siempre el por qué. Ahí entra la documentación.
- 🧠 Conocimiento en el mundo: cuanto menos tengas que recordar, más capacidad mental tienes para resolver el problema en el que estás.
Vale, hasta aquí tenemos lo básico sobre documentación, pero ¿como trasladamos eso a nuestros proyectos? ¿Cómo hacemos para que la documentación sea efectiva?
Documentación en proyectos: lo básico (y suficiente)
📘 README
El README es la puerta de entrada al proyecto. Tiene que permitir que alguien nuevo entienda lo esencial, de eso ya hablamos en como escribir un Readme que mole.
Lo esencial es que el primer párrafo sea una explicación clara y concisa de lo que hace el proyecto: Microservicio que recolecta, transforma y envía métricas de producto.
Una sección de setup del proyecto, para ello puedes usar Makefiles.
Y algunos links a la documentación: tipico «how to probar en local», «how to configurar la base de datos,…» y links a los ADR
🧪 How-tos: recetas prácticas
A veces necesitas dejar instrucciones específicas: cómo ejecutar tests e2e, cómo levantar un entorno, cómo configurar RabbitMQ…
En vez de llenarlo todo en el README, crea documentos tipo:
docs/how-to/run-e2e-tests.md
docs/how-to/deploy-staging.md
Y enlázalos. Así mantienes orden sin perder claridad. En nuestro caso tenemos una carpeta docs en el proyecto y dentro una carpeta how to…
ADRs: decisiones que merecen ser recordadas
Hay momentos en los que el equipo toma decisiones importantes que no se ven en el código.
Cosas como:
- “Vamos a usar Redis en lugar de Memcached”
- “Dividimos el monolito en microservicios”
- “Usamos WebSockets en vez de polling”
Decisiones que no son obvias y que probablemente alguien preguntará en 6 meses:
“¿Y por qué hicimos esto así?”
Ahí es donde entran los ADRs: Architectural Decision Records.
Los Architectural Decision Records (ADRs) son documentos breves para explicar decisiones importantes del proyecto. Cuándo, por qué, qué opciones se evaluaron, qué se eligió y por qué.
Ejemplo:
Title: Usamos Redis como caché de sesión
Date: 2024-11-01
Context: Necesitamos almacenar sesiones de usuarios autenticados
Options considered: Redis, Memcached, base de datos
Decision: Redis, por facilidad de integración y soporte de expiración
Son importantes porque la arquitectura no se entiende solo con código.
Y si no documentas las decisiones, estás condenado a repetir las discusiones. Además esas decisiones no están grabadas en piedra, se pueden cambiar y crear un nuevo ADR que mejore al anterior (solo tenemos que acordarnos de marcar los antiguos como deprecated)
Un ADR explica una decisión técnica que afecta al proyecto y que tiene implicaciones relevantes a medio/largo plazo.
💬 RFCs: cuando aún no está decidido
Los RFCs (Request for Comments) son propuestas de cambio que todavía se están discutiendo. Sirven para recoger feedback antes de tomar una decisión.
El flujo típico es:
- Se crea un RFC: Normalmente creamos un google docs, porque es más fácil comentar y añadir imágenes/diagramas, pero se podría hacer en git dentro del repositorio tambien.
- Se comparte al equipo: Hay que recordarlo muchas veces, porque tenemos tiempo o estamos. otra cosa, así que hay que recordar. En algunos casos he visto que en el template c
- Se discute (sin prisa)
- Se decide → se convierte en ADR, o se descarta
Útil para decidir cosas como: ¿Migramos a PostgreSQL?¿Adoptamos TypeScript en este repo?¿Cambiamos la arquitectura de colas?
Un RFC debe responder preguntas como:
- ¿Qué problema estamos intentando resolver?
- ¿Qué soluciones se han evaluado?
- ¿Cuál es la propuesta?
- ¿Qué impacto tiene?
- ¿Qué necesitamos para implementarlo?
¿Y qué pasa con los comentarios en el código?
La regla de oro: el mejor comentario es el que no hace falta. Los comentarios en el código son un tema sensible: todos los hemos visto mal usados, pero bien empleados, son una herramienta muy poderosa. Los comentarios son como el ajo: en su justa medida, elevan el plato. Pero si abusas… todo huele raro.
Significa: comenta solo cuando realmente aporta algo que el código no puede expresar por sí mismo.
// Usamos esta transformación para evitar datos nulos en el pipeline (ref: BUG-221)
const sanitized = sanitizeData(input)
✅ Explica el por qué, no el cómo
✅ Añade referencias si aplica
✅ Borra los comentarios que ya no tienen sentido
Por ejemplo: para referenciar bugs, decisiones o tickets, para explicar el por qué, no el cómo, para ayudar en código especialmente raro
Las buenas prácticas en este punto serían:
- Si algo necesita un comentario, pregúntate primero si no deberías renombrar una variable, extraer una función o reorganizar el código.
- Si decides comentar, hazlo bien: claro, breve y al grano.
- Evita comentarios tipo «esto es un poco hacky jeje» — eso no ayuda a nadie
Y no olvides lo más importante…
La documentación no es un objetivo. Es una herramienta para reducir fricción.
En equipos de ingeniería solemos repetir eso de “el código se explica solo”.
Y sí, ojalá. Pero la realidad es que:
- El código no siempre explica por qué se tomó una decisión
- La estructura del proyecto no siempre dice cómo empezar a contribuir
- La gente cambia, se va, entra nueva… y sin documentación, todo se pierde
Documentar no es escribir por escribir.
Es una forma de:
🧠 Reducir carga mental
🧭 Dar dirección y contexto
🔄 Evitar errores repetidos
🤝 Facilitar la colaboración
🚀 Acelerar el onboarding de nuevos miembros
📚 Dejar un legado técnico que se puede mantener
No se trata de escribir novelas, sino de dejar las pistas necesarias para que alguien (o tu yo del futuro) entienda, contribuya y mantenga el sistema sin sufrir.
Hazla útil, cercana, viva y accesible. No escribas por cumplir, escribe para ayudar.
Jesús L.C. - Apuntes de un aprendiz 
Comenta la entrada