Ir al contenido
Documentación

Documentación que coincide con la realidad

La documentación escrita de memoria está equivocada en un mes y todo el mundo aprende a desconfiar de ella. La documentación generada a partir del código, con pruebas, sí merece conservarse.

Qué hay en esta categoría

Documentos con una tarea que cumplir

Cada uno existe para responder a una pregunta que alguien va a hacer de verdad.

Documentación C4

Vistas de contexto, contenedores y componentes, cada una derivada del código y cada una trazable hasta él.

Registros de decisiones de arquitectura

Por qué el sistema es como es: la decisión, las alternativas y lo que costó. El documento que le ahorra un mes a la siguiente persona.

Diagramas de secuencia

Los flujos que importan, dibujados tal como se ejecutan de verdad, incluidos los caminos de error que se olvidan documentar.

Manuales de despliegue

Qué hacer para publicar y qué hacer cuando la publicación sale mal, escrito para que lo siga alguien cansado y solo.

Registro de interfaces

Cada API y punto de integración, qué promete, quién depende de él y qué se rompe si cambia.

Documentación operativa

Dónde se ejecutan las cosas, qué comprobar cuando se portan mal y qué alarmas significan algo.

Cómo se ejecuta el trabajo de documentación

  1. Generada del sistema, no de la memoria

    El procedimiento lee primero el código. Lo que no encuentra lo marca como desconocido en lugar de inventarlo.

  2. Cada afirmación lleva su fuente

    Un elemento de un diagrama que no se puede trazar hasta un archivo es un dibujo, no documentación.

  3. Los huecos se declaran, no se rellenan

    Donde el sistema es realmente confuso, el documento lo dice. Eso es más útil que una suposición segura y más seguro para actuar.

  4. Revisable por una persona

    La documentación es de lo mejor que se puede mandar a revisión de expertos: los errores en ella son baratos de arreglar y caros de dejar.

Cuándo invertir en documentación

Puede esperar si

El producto puede no existir dentro de tres meses

Una sola persona lo construye y lo opera todo

La arquitectura sigue cambiando cada semana

Hágalo ahora si

Está incorporando desarrolladores o un proveedor

Un cliente o un inversor está haciendo diligencia debida

La única persona que lo entendía se va

Va a dejar que un agente de IA lo refactorice

Elija la categoría que corresponde a su preocupación

Describa la situación con sus palabras y vea el procedimiento —y su coste— antes de gastar nada.