Documentación y decisiones

El oficio: documentar para el lector, no para el autor

El código dice qué hace un sistema; la documentación dice por qué existe, cómo se usa y cómo se decidió. Un buen documento no es el más largo, sino el que permite a una persona concreta conseguir algo concreto sin tener que preguntar a nadie. Quien escribe documentación técnica trabaja con tres ideas fijas: conocer al lector, dar a cada documento un único propósito y mantener lo escrito, porque la documentación desfasada es peor que la ausente: engaña.

Conocer a la audiencia

Antes de escribir una línea conviene responder a cuatro preguntas:

1. ¿Quién lo va a leer? Perfil, conocimiento previo y vocabulario.
2. ¿Para qué? Qué quiere conseguir después de leerlo.
3. ¿En qué momento? Con calma, o con el sistema caído a las tres de la madrugada.
4. ¿Dónde lo buscará? Si no sabe que existe, no lo leerá.

Diátaxis: cuatro tipos de documento

El marco Diátaxis (Daniele Procida) sostiene que toda documentación técnica responde a cuatro necesidades distintas y que cada una exige un estilo propio. Mezclarlas es la causa más común de documentación confusa.

Cómo reconocer un tipo mal escrito

• Un tutorial que se detiene a explicar la arquitectura: el alumno pierde el hilo. La explicación va en otro sitio y se enlaza.
• Una guía práctica que empieza por «Qué es un contenedor»: quien llega busca resolver algo, no aprender conceptos.
• Una referencia con opiniones y consejos: debe ser neutral y exhaustiva.
• Una explicación que se convierte en lista de pasos: pierde su razón de ser.

Principios por tipo

ADR: registro de decisiones de arquitectura

Michael Nygard popularizó el Architecture Decision Record: un documento corto, fechado e inmutable que deja constancia de una decisión importante. Su valor llega meses después, cuando alguien pregunta «¿por qué se hizo así?» y nadie lo recuerda.

Qué merece un ADR

Una decisión es candidata si cumple alguna de estas condiciones:

• Es costosa de revertir (lenguaje, base de datos, proveedor, estilo de arquitectura).
• Afecta a varios equipos o fija una norma que todos deben seguir.
• Tiene alternativas razonables y alguien, en el futuro, las propondrá de nuevo.
• Resuelve una tensión entre atributos de calidad (rendimiento frente a coste, por ejemplo).

No merece ADR lo que se decide de nuevo sin dolor cada semana ni lo que es evidente.

Un ADR completo de ejemplo

# ADR-014: Usar PostgreSQL como base de datos principal
 
- Estado: Aceptado
- Fecha: 2026-03-12
- Decisores: equipo de plataforma
- Sustituye a: ADR-003 (uso de ficheros planos)
 
## Contexto
La aplicación necesita transacciones con consistencia fuerte, consultas
con uniones entre cinco entidades y búsqueda de texto básica. El equipo
tiene experiencia con SQL y no con sistemas de documentos. Se prevé un
volumen de datos moderado durante los dos próximos años.
 
## Opciones consideradas
1. PostgreSQL.
   + Transacciones ACID, SQL estándar, extensiones, amplio soporte.
   - Escalado horizontal de escritura más laborioso.
2. Base de datos de documentos.
   + Esquema flexible, escalado horizontal sencillo.
   - Las uniones y las transacciones multidocumento son menos naturales.
3. Mantener ficheros planos.
   + Sin infraestructura nueva.
   - No admite concurrencia ni consultas complejas.
 
## Decisión
Se adopta PostgreSQL gestionado por el proveedor de nube.
 
## Consecuencias
- Se obtiene consistencia transaccional y consultas flexibles.
- Se asume la gestión de migraciones de esquema y de copias de seguridad.
- Si el volumen de escritura crece mucho más de lo previsto, habrá que
  revisar esta decisión (réplicas o particionado).

Ciclo de vida de un ADR

La regla de oro: un ADR aceptado no se reescribe. Si la decisión cambia, se redacta uno nuevo que referencia al anterior y este queda marcado como sustituido. Así el historial cuenta cómo evolucionó el razonamiento, no solo el estado actual.

Plantillas habituales

Buenas prácticas

• Se escribe en el mismo repositorio y se revisa por pull request: la discusión queda enlazada.
• Un fichero por decisión, con numeración correlativa y un nombre descriptivo.
• Se redacta cuando se decide, no un año después.
• Se anotan las alternativas descartadas y por qué: es lo que más ahorra discusiones repetidas.
• Se mantiene un índice con el estado de cada uno.

Arquitectura documentada: C4 y arc42

Modelo C4

Simon Brown propone describir la arquitectura en cuatro niveles de zoom, como un mapa que se puede acercar o alejar.

Reglas para que un diagrama C4 se entienda: título y leyenda en todos, cada elemento con nombre, tipo y una línea de descripción, cada flecha con verbo y tecnología («Lee pedidos, HTTPS») y ninguna caja sin explicar. En C4, «contenedor» no significa contenedor de Docker: es una unidad desplegable o un almacén de datos.

arc42

arc42 (Gernot Starke y Peter Hruschka) es una plantilla de doce apartados que sirve de lista de comprobación para no olvidar nada al documentar una arquitectura. No hay que rellenarlos todos: se completa lo que aporta valor y se omite el resto con una nota.

C4 y arc42 se complementan: C4 ofrece la notación de los diagramas y arc42 la estructura del documento donde viven.

Qué diagrama para qué pregunta

Los diagramas se mantienen como texto (Mermaid, PlantUML, Structurizr) siempre que sea posible: se versionan, se revisan en el pull request y no se quedan obsoletos en una herramienta aparte.

Documentación como código

La idea es tratar los documentos igual que el software: control de versiones, revisión, pruebas y publicación automática.

• Mismo repositorio que el código que describen, para que cambien juntos.
• Revisión en el mismo pull request: si el cambio modifica un comportamiento, el cambio incluye su documentación.
• Formato de texto plano (Markdown, reStructuredText, AsciiDoc): diferencias legibles y fusiones fáciles.
• Comprobaciones automáticas: enlaces rotos, ortografía, guía de estilo (con una herramienta como Vale), formato.
• Ejemplos que se ejecutan: los fragmentos de código de la documentación se prueban en integración continua.
• Referencia generada a partir de la fuente de verdad: el contrato de la API (OpenAPI), los comentarios de código o el esquema de datos.

Qué se genera y qué se escribe

Lo generado no se edita a mano: se corrige en la fuente.

Documentación dentro del código

Los comentarios no sustituyen a los documentos, pero tienen un papel concreto:

• Documentación de API pública (docstrings, JSDoc, rustdoc): qué hace, parámetros, errores, un ejemplo mínimo.
• Comentarios de porqué: explican una decisión no evidente, un truco o una restricción externa.
• Nada de comentarios que repiten el código («incrementa i»): envejecen y no aportan.

/**
 * Devuelve el precio con impuestos aplicados.
 *
 * @param base Precio sin impuestos, en céntimos.
 * @param tipo Tipo impositivo entre 0 y 1 (0,21 para el 21 %).
 * @throws RangeError si `tipo` está fuera del intervalo permitido.
 * @example precioConImpuestos(1000, 0.21) // 1210
 */
export function precioConImpuestos(base: number, tipo: number): number {
  if (tipo < 0 || tipo > 1) throw new RangeError("tipo fuera de rango");
  return Math.round(base * (1 + tipo));
}

Cuando el código necesita un comentario largo para entenderse, a veces la mejor documentación es renombrar o extraer una función.

README y documentos de entrada

El README es la puerta de entrada y se juzga por un criterio: ¿puede alguien nuevo poner el proyecto en marcha en diez minutos?

Otros ficheros de repositorio con función propia: CONTRIBUTING (cómo proponer cambios), CHANGELOG (qué cambió en cada versión), SECURITY (cómo comunicar vulnerabilidades) y CODEOWNERS (quién revisa qué).

Runbooks

Un runbook es una guía para quien opera el sistema y tiene prisa. Debe poder seguirse con estrés y sin contexto:

# Runbook: la cola de pedidos no se vacía
 
Síntoma: la alerta "cola de pedidos creciendo" lleva más de 10 minutos activa.
Impacto: los pedidos se confirman con retraso.
 
1. Comprobar si los consumidores están vivos (panel de la cola).
2. Si no lo están: reiniciar el servicio de consumo y observar 2 minutos.
3. Si lo están pero no avanzan: revisar el último error en los registros.
4. Si el error es de la base de datos: escalar a guardia de datos.
 
Cuándo escalar: si no hay mejora tras 15 minutos.
Cómo comprobar la recuperación: la cola baja de 100 mensajes.

Características: síntoma y comprobación concretos, pasos numerados, condiciones de escalado y criterio de recuperación.

Escribir bien: claridad y estilo

Principios de redacción técnica

• Una idea por frase y frases cortas.
• Voz activa y orden de acción: «Ejecuta el comando» y no «El comando debe ser ejecutado».
• Imperativo en los pasos, y un único paso por cada acción.
• Vocabulario consistente: el mismo término para la misma cosa en todo el texto. Cambiar de sinónimo confunde.
• Ejemplos concretos antes que descripciones abstractas.
• Lo más importante, primero (pirámide invertida): condiciones previas y advertencias antes del paso, no después.
• Texto accesible: encabezados jerárquicos, texto alternativo en imágenes, enlaces con texto descriptivo (no «pulsa aquí»).
• Sin jerga innecesaria; los acrónimos se explican la primera vez.

Estructura que se puede recorrer

La gente no lee la documentación, la escanea. Ayudan los títulos descriptivos, los párrafos breves, las listas, las tablas para comparar y los bloques de código para lo que se copia. Cada página debería empezar diciendo para qué sirve.

Una guía práctica bien formada

## Configurar el envío de correos
 
Antes de empezar: necesitas permiso de administrador y la clave de acceso del proveedor.
 
1. Abre el fichero de configuración del entorno.
2. Añade la clave de acceso en la variable correspondiente.
3. Reinicia el servicio.
4. Envía un correo de prueba desde la pantalla de ajustes.
 
Resultado esperado: el correo de prueba llega en menos de un minuto.
Si no llega: consulta "Diagnosticar problemas de envío".

Mantener la documentación viva

La documentación se pudre si nadie es responsable de ella. Estrategias que funcionan:

Preguntas repetidas como señal

Si la misma pregunta llega por mensaje tres veces, falta documentación o no se encuentra. Responder enlazando a un documento (y escribiéndolo si no existe) convierte cada pregunta en una mejora permanente.

Especificaciones y documentación de diseño

Un documento de diseño (a veces llamado RFC o propuesta técnica) se escribe antes de implementar algo de cierto tamaño para ordenar el pensamiento y recoger opiniones.

Cuando el diseño se aprueba, las decisiones importantes se destilan en ADR y el documento se archiva: el ADR es lo que perdura.

Cómo elegir qué documentar

La documentación tiene coste de escritura y de mantenimiento. Un criterio práctico:

Lista de comprobación

• Cada documento declara su propósito en la primera línea.
• Cada documento pertenece a un único tipo de Diátaxis.
• El README se ha seguido desde cero en una máquina limpia.
• Las decisiones difíciles de revertir tienen su ADR.
• Los diagramas tienen título, leyenda y están en texto versionable.
• La referencia se genera de la fuente de verdad.
• La documentación se actualiza en el mismo pull request que el código.
• Hay un propietario y una forma de saber qué está obsoleto.

Errores y antipatrones

• Documentar el «qué» y callar el «por qué». El código ya cuenta lo primero.
• El documento único e interminable. Nadie lo lee, nadie lo actualiza.
• Documentación aparte del código, en una herramienta que nadie abre: se desfasa el día siguiente.
• Editar un ADR antiguo para que parezca que siempre se pensó así. Se pierde la historia del razonamiento.
• ADR sin alternativas: una decisión sin opciones descartadas parece una imposición.
• Diagramas sin leyenda ni título, con flechas sin significado.
• Instrucciones nunca probadas. El README que empieza con un paso inexistente espanta a quien llega.
• Documentar tras el hecho. Lo que no se escribe cuando se decide, se reescribe mal después.
• Capturas de pantalla para todo: se quedan obsoletas con cada cambio visual. Mejor texto y, si hace falta, una imagen aclaratoria.
• Culto al volumen. Medir la documentación por páginas en lugar de por problemas resueltos.