Ir al contenido
Documentación

Documentación en la que alguien va a confiar

Un documento que fue cierto una vez y ahora está equivocado es peor que no tener documento, porque alguien actuará según él. Qué se escribe y quién lo escribe depende del nivel.

Qué incluye

Los documentos que merece la pena tener

Arquitectura

De qué está hecho el sistema y cómo se relacionan sus partes, con un detalle que sobreviva a los próximos tres meses.

Infraestructura y entrega

Dónde se ejecuta, cómo llega un cambio a producción y qué hacer cuando eso falla a las dos de la mañana.

Decisiones y su porqué

El razonamiento detrás de las elecciones, que es la parte que siempre se pierde y siempre hace falta después.

Incorporación

Lo que un desarrollador o un agente nuevo necesita saber antes de tocar nada.

Quién la escribe

La respuesta honesta depende del nivel

  1. Nivel de asesoría

    Leo documentos y los comento, explico qué debería haber en ellos y le doy el prompt o el encargo para producirlos. No escribo la documentación de su proyecto como entregable.

  2. Nivel de dirección

    Exijo documentación al equipo, pongo la tarea y acepto el resultado. No la produzco yo en su lugar.

  3. Nivel de Vibe Coding

    La documentación forma parte de la entrega. Código, infraestructura y decisiones importantes se escriben mientras se trabaja.

  4. Por qué importa la diferencia

    Anunciar documentación como entregable en todos los niveles sería venderle algo que el precio no contiene.

Qué esperar

No espere

Un documento de cien páginas hecho una vez y nunca actualizado

Documentación de un sistema que no he leído

Documentos escritos como entregable en el nivel de asesoría

Espere

Documentos lo bastante cortos como para que alguien los lea

Afirmaciones que se pueden comprobar contra el sistema en marcha

Decisiones registradas con su razonamiento y no solo con el resultado

En el nivel superior, documentación publicada junto con el trabajo

Empiece por el área que más le preocupa

Elija el nivel de implicación que encaje, describa su producto y empezamos por ahí.