¿Alguna vez abriste el README de un proyecto, lo leíste completo y aun así no supiste cómo ponerlo en marcha? Sí, pasa. El problema casi nunca es la falta de documentación. Es la documentación en la que nadie confía.
El problema no es la falta de documentación, sino la documentación en la que nadie confía
Todo equipo tiene una carpeta docs/ llena. Nadie la lee. Porque la primera vez que alguien siguió un paso a paso y estaba equivocado, la documentación se convirtió en ficción. Desde entonces, todo el mundo va directo al código o pregunta en el chat.
La buena documentación no es documentación extensa. Es la que lees y en la que confías. Todo lo demás de este texto trata sobre cómo ganarse esa confianza.
El README responde las primeras 5 preguntas
Quien abre tu repo llega con cinco preguntas, casi siempre en este orden:
- ¿Qué es esto?
- ¿Cómo lo ejecuto localmente?
- ¿Cómo ejecuto las pruebas?
- ¿Cómo contribuyo?
- ¿Dónde pido ayuda cuando me atasco?
Si el README responde esas cinco preguntas en treinta segundos de lectura, cumplió su función. Lo demás es un extra. Y cuidado: todo lo que colocas antes de esas respuestas —badges bonitos, la historia del proyecto, un diagrama de arquitectura— se convierte en un obstáculo entre la persona y lo que necesita. Déjalo más abajo.
Explica el porqué, no solo el cómo
El cómo ya lo cuenta el código. retry(3) es obvio para cualquiera que lea la línea. Lo que nadie puede adivinar es por qué tres y no cinco. O por qué existe el retry, para empezar.
La documentación que solo describe lo que hace el código es redundante y envejece rápido: cambia el código y la documentación miente. La documentación que explica la decisión sobrevive a la refactorización. Así que registra el motivo, el trade-off, ese enfoque que intentaste y abandonaste. Eso es algo que git blame no te entrega a las dos de la mañana.
La documentación lejos del código es documentación muerta
La documentación que vive en un Confluence olvidado muere al día siguiente del deploy. Nadie actualiza lo que no ve en el flujo normal de trabajo.
Acerca la explicación a aquello que describe:
- README en la raíz de cada módulo, no solo en la del repo
- comentario encima de la función extraña, explicando qué la hace extraña
- un ADR corto (una decisión, media página) en la propia carpeta del proyecto
Cuanto menor sea la distancia entre el código y la explicación, mayores serán las probabilidades de que la explicación siga siendo verdadera cuando cambie el código, porque está ahí, en el mismo diff, pidiendo que la actualicen.
Un ejemplo vale más que tres párrafos
Nadie lee la descripción textual de un parámetro. Todo el mundo busca el ejemplo, lo copia y lo adapta. Un bloque de código que funciona enseña más rápido que cualquier prosa elaborada.
Mejor aún: un ejemplo que se prueba. Si el snippet del README se ejecuta en el CI —aunque sea una prueba sencilla que solo ejecute el ejemplo— nunca miente durante mucho tiempo. La documentación que rompe el build cuando queda desactualizada es documentación que se mantiene casi sola. Es el truco más barato para evitar el deterioro del código y la documentación.
La documentación que miente es peor que la que falta
La documentación que falta es honesta: sabes que tendrás que preguntar o leer el código. La documentación que miente cuesta una hora siguiendo un camino que ya no existe y, además, destruye la confianza en todo lo demás que está escrito.
Así que trata la documentación como código:
- si eliminaste una feature, elimina su documentación en el mismo PR
- si cambiaste el paso, cambia el texto ahora, no "después"
- si no vas a mantenerla, elimínala
Un README de tres líneas verdaderas vale más que treinta líneas de mentiras. Escribe menos, pero escribe lo que sea verdad hoy. La documentación no muere por ser corta: muere por ser falsa.
