La documentación que alguien va a leer
Casi toda la documentación que se escribe por prolijidad no se lee y queda vieja. La que sirve responde una pregunta que alguien tuvo de verdad, vive cerca del código y se puede verificar copiando y pegando.
Un README de cuarenta líneas que explica qué es Node, cómo se instalan las dependencias y qué
hace npm start. Nadie lo lee, porque todo eso ya se sabe. Y cuando alguien busca lo que
realmente necesita —por qué hay dos bases de datos, qué variable de entorno falta, cómo se
genera el token de prueba— no está.
La documentación no se mide en páginas: se mide en preguntas que dejaron de hacerse. Si nadie hacía esa pregunta, escribir la respuesta no ayudó a nadie y ahora hay una línea más que puede quedar vieja.
Qué merece estar escrito
| Tipo | Ejemplo | ¿Vale la pena? |
|---|---|---|
| Lo que el código ya dice | «La función calcularTotal calcula el total» | No: se desactualiza y no aporta |
| Lo genérico de la herramienta | «Instalar dependencias con el gestor de paquetes» | No: está en la documentación oficial |
| El porqué de algo raro | «Este reintento existe porque el proveedor devuelve 502 en el primer pedido del día» | Sí: no se deduce de ningún lado |
| Lo que hay que saber antes de empezar | «Necesitás credenciales de prueba, se piden acá» | Sí: es lo primero que frena a alguien nuevo |
| Procedimientos que se hacen poco | «Cómo rotar la clave del servicio de pagos» | Sí: justo por hacerse poco, nadie se acuerda |
| Decisiones y sus alternativas | «Elegimos colas en vez de llamadas directas porque…» | Sí: evita que se rediscuta cada seis meses |
Dónde va cada cosa
La documentación que vive lejos de lo que describe se desactualiza sin que nadie lo note:
| Qué | Dónde | Por qué ahí |
|---|---|---|
| Cómo levantar el proyecto | README de la raíz | Es lo primero que abre alguien nuevo |
| Por qué una línea rara hace lo que hace | Un comentario en esa línea | Es el único lugar donde se lee en el momento justo |
| Cómo funciona un módulo | Un archivo dentro de ese módulo | Si el módulo se borra, su documentación se va con él |
| Por qué se tomó una decisión | Un registro de decisiones en el repositorio | Sobrevive a la gente y se puede enlazar |
| Un procedimiento operativo | Una guía paso a paso, con comandos copiables | Se ejecuta bajo presión y no es momento de interpretar |
Antes de seguir, predecí
Cómo se escribe algo que se pueda seguir
Plantilla
Guía de un procedimiento
Para qué sirve y cuándo se usa
Una frase. Por ejemplo: rotar la clave del servicio de pagos, cada 90 días o ante una sospecha de filtración.
Sin esto, quien la encuentra no sabe si es la guía que necesita.
Qué necesitás antes de empezar
Accesos, permisos, variables, herramientas instaladas. Todo lo que, si falta, te frena a la mitad.
Es la sección que evita quedarse trabado en el paso 4 esperando un permiso.
Los pasos, con comandos exactos
Numerados, copiables, con los valores de ejemplo marcados claramente para reemplazar.
Nada de «configurar el servicio»: el comando o la ruta exacta de la pantalla.
Cómo verificar que salió bien
Qué mirar y qué tiene que decir. Un comando cuya salida se pueda comparar.
Sin verificación, quien ejecuta no sabe si terminó o si rompió algo en silencio.
Qué hacer si sale mal
Cómo volver atrás y a quién avisar.
La sección que más se agradece y que casi nunca está.
Cuándo escribirla
El mejor momento casi nunca es «cuando haya tiempo»:
- Justo después de sufrirlo. Cuando te costó cuatro horas entender algo, tenés fresco exactamente lo que no estaba claro. Dos días después ya te parece obvio y escribís peor.
- Cuando alguien pregunta por segunda vez. La primera vez se contesta; la segunda se contesta y se escribe, y se manda el enlace.
- En el mismo cambio que lo vuelve viejo. Si tocás el procedimiento, tocás la guía. Es la única disciplina que evita la documentación mentirosa.
Lo que preguntan sobre esto
Cierre
Autoevaluación
¿Lo entendiste?
Práctica