Definición
La documentación técnica es lo que alguien necesita saber para trabajar en un sistema y no puede deducir leyendo el código.
Esa frase contiene la clave, porque delimita lo que merece la pena escribir. El código ya dice qué hace. Lo que no dice nunca es:
- Por qué se tomó esa decisión y qué alternativas se descartaron.
- Cómo se pone en marcha el proyecto desde cero.
- Qué es peligroso tocar y por qué.
- Qué depende de qué fuera del propio código.
Documentar lo primero —repetir en prosa lo que hace una función— es trabajo perdido: envejece de inmediato y nadie lo lee.
Lo que sí merece la pena
El fichero de bienvenida del proyecto. Qué es esto, cómo se instala, cómo se arranca, cómo se despliega. Es lo más valioso por unidad de esfuerzo, y su prueba de calidad es concreta: alguien nuevo debe poder arrancar el proyecto siguiéndolo, sin preguntar.
Decisiones de arquitectura. Un párrafo por decisión importante: qué se decidió, por qué, qué se descartó. Dentro de un año, evita rehacer un debate ya resuelto o deshacer algo que estaba puesto por una razón.
Documentación de la API, si otros la consumen. Endpoints, parámetros, errores y ejemplos reales.
Procedimientos operativos. Cómo desplegar, cómo restaurar una copia, qué hacer si falla el proceso nocturno. Esto se necesita precisamente cuando hay prisa y nervios, que es cuando peor se improvisa.
Peculiaridades y trampas. El conocimiento que solo se adquiere sufriendo: que este proceso rompe si se ejecuta dos veces, que este campo tiene otro nombre por razones históricas, que este sistema espera las fechas en otra zona horaria.
Esa última categoría es la que más valor tiene y la que casi nadie escribe.
Ejemplo práctico
En proyectos con varios sistemas conectados, la documentación que de verdad se usa no es un manual: es un registro de decisiones y de trampas encontradas.
Lo que aprendí: funciona muy bien mantener un documento cronológico por proyecto donde se anota, con fecha, qué se hizo, por qué y qué salió mal. No es un manual pulido y no pretende serlo. Su utilidad aparece meses después, cuando algo se comporta raro y ese registro contiene la explicación exacta — normalmente escrita el día que costó tres horas descubrirla.
Y hay una segunda utilidad menos evidente: obliga a pensar mientras se escribe. Redactar por qué se hizo algo destapa a veces que la razón ya no se sostiene.
El segundo aprendizaje, sobre por qué la documentación fracasa: no fracasa por falta de tiempo, fracasa porque se queda obsoleta y entonces engaña. Una documentación desactualizada es peor que ninguna: alguien la sigue, no funciona, y pierde la confianza en todo lo demás.
Dos hábitos lo evitan:
Que viva junto al código, en el mismo repositorio, para que se actualice en el mismo cambio que la vuelve falsa. Ver revisión de código.
Poca y verdadera antes que mucha y dudosa. Un fichero de bienvenida correcto vale más que cincuenta páginas que nadie ha leído desde hace dos años.
Y una advertencia sobre los comentarios en el código: un comentario que explica qué hace la línea siguiente sobra, y estorba cuando el código cambia y él no. El comentario que vale explica por qué: «se hace en dos pasos porque la API rechaza más de cien elementos por llamada». Esa información no está en ningún otro sitio.
Errores comunes
- Documentar el qué en vez del porqué.
- Dejarla obsoleta, que es peor que no tenerla.
- Guardarla fuera del repositorio, donde se olvida.
- Instrucciones de arranque que no funcionan desde cero.
- No documentar los procedimientos de emergencia, que se necesitan bajo presión.
- Perder el conocimiento de las trampas cuando alguien se va.
- Documentar demasiado y que nadie lea nada.
- Comentarios que repiten el código.
Cuándo escribirla
En el momento, no al final. La documentación que se pospone a «cuando terminemos» no se escribe nunca, y el detalle que valía la pena anotar ya se ha olvidado.
La prueba que mide si la tuya sirve: dale el proyecto a alguien que no lo conozca y pídele que lo arranque. Todo lo que tenga que preguntar es exactamente lo que falta por documentar.
