Redacción técnica: documentación que la gente sí lee

La documentación no falla porque los ingenieros no sepan escribir, sino porque escriben para el público equivocado en el momento equivocado. Un documento de diseño de 2000 palabras redactado después de fusionar el código es arqueología. Un README que explica qué hace el proyecto pero no cómo ejecutarlo es decoración. La brecha entre la documentación que existe y la documentación que ayuda tiene que ver por completo con el momento, la estructura y la empatía hacia quien lee.

La buena documentación responde una pregunta concreta, para una persona concreta, en un momento concreto de su flujo de trabajo. Todo lo demás es ruido.

Los cuatro tipos de documentación

No toda la documentación cumple el mismo propósito. Tratar un tutorial como si fuera una referencia (o al revés) produce documentos que fallan en ambos frentes.

<!-- ❌ Mixes tutorial with reference — confusing for both audiences -->
# API Guide
To use our API, first get an API key from the dashboard.
POST /api/users accepts { name: string, email: string }...
Here's a fun history of how we built the API...
 
<!-- ✅ Separate documents for separate purposes -->
# Getting Started (tutorial)
# API Reference (reference)
# Architecture Decision: REST vs GraphQL (explanation)

Cuando te sorprendas alternando entre enseñar y enumerar, divide el documento. Cada tipo tiene un lector distinto con necesidades distintas.

Registros de decisiones de arquitectura

Los ADRs son la documentación de mayor impacto que puede escribir un equipo de ingeniería. Capturan el porqué detrás de las decisiones: el contexto, las restricciones y las alternativas que dieron forma a la base de código.

# ADR-007: Use PostgreSQL for Primary Datastore
 
## Status
Accepted
 
## Context
We need a primary datastore for the user service.
Current load: ~500 writes/sec, ~5000 reads/sec.
Team has deep PostgreSQL experience. Two engineers
have DynamoDB experience.
 
## Decision
Use PostgreSQL 14 with read replicas.
 
## Alternatives Considered
- **DynamoDB**: Lower ops overhead but vendor lock-in.
  Team experience gap would slow initial development.
- **MySQL**: Similar capabilities, but our tooling and
  migration scripts assume PostgreSQL.
 
## Consequences
- Must manage connection pooling (PgBouncer)
- Read replicas add ops complexity
- Team can reuse existing migration patterns
- Avoids vendor lock-in in the data layer

Las secciones clave son Context y Alternatives Considered. Sin contexto, los ingenieros que lleguen después no podrán juzgar si la decisión sigue vigente. Sin alternativas, no podrán evaluar los compromisos cuando las circunstancias cambien.

Cómo escribir ADRs efectivos

// ❌ Vague context — doesn't help future decisions
interface BadADR {
  context: "We needed a database";
  decision: "We chose PostgreSQL";
  // Missing: why not alternatives? What constraints existed?
}
 
// ✅ Specific context — enables revisiting the decision
interface GoodADR {
  context: {
    loadPattern: "500 writes/sec, 5000 reads/sec";
    teamExperience: "3 senior engineers with PostgreSQL";
    constraints: ["no vendor lock-in", "ACID required"];
    timeline: "must ship in 6 weeks";
  };
  decision: "PostgreSQL 14 with read replicas";
  alternatives: Array<{
    option: string;
    pros: string[];
    cons: string[];
    reason_rejected: string;
  }>;
}

Trata los ADRs como inmutables. Cuando una decisión queda obsoleta, escribe un nuevo ADR que haga referencia al anterior. Nunca edites un ADR pasado: es un registro histórico de lo que se sabía en ese momento.

Una estructura de README que funciona

La mayoría de los README están vacíos o son un muro de texto. Un buen README responde cinco preguntas en orden, y la mayoría de los desarrolladores solo necesitan las tres primeras.

# Project Name
 
One sentence: what it does and who it's for.
 
## Quick Start
 
Three commands or fewer to go from clone to running.
 
## Development
 
How to run tests, lint, and build locally.
 
## Architecture
 
High-level overview: key directories, data flow,
external dependencies.
 
## Deployment
 
How to deploy. Environment variables. Infrastructure.

# ❌ "Check the wiki for setup instructions"
# (The wiki is outdated, has broken links, and contradicts itself)
 
# ✅ Quick Start that actually works
git clone git@github.com:team/project.git
cd project
cp .env.example .env
docker compose up -d

La sección Quick Start es la más importante. Si un nuevo miembro del equipo no puede pasar de git clone a tener la aplicación funcionando en menos de 10 minutos, el README ha fracasado.

Cómo escribir comentarios en el código

Los comentarios en el código deben explicar el porqué, no el qué. El código ya explica qué hace. Un comentario que repite el código añade ruido. Un comentario que explica el razonamiento se vuelve invaluable a la hora de depurar.

// ❌ Restates the code — adds nothing
// Increment counter by 1
counter += 1;
 
// ✅ Explains regulatory/business context
// GDPR Article 17: must purge all PII within 30 days
// of deletion request. The grace period allows undo.
const PURGE_DELAY_DAYS = 30;
 
// ✅ Explains non-obvious technical decisions
// Using requestAnimationFrame instead of setTimeout
// because setTimeout(0) can be throttled to 4ms+ in
// background tabs (Chrome 88+), causing visible jank
// when the tab regains focus.
requestAnimationFrame(flushUpdates);

Los mejores comentarios responden a la pregunta: "¿por qué alguien cambiaría esto, y qué necesitaría saber?". Si la respuesta es "nada, es obvio", omite el comentario.

Documentación en línea en las APIs

La documentación de una API vive más cerca del código cuando se genera a partir de él. Las anotaciones de JSDoc, TypeDoc u OpenAPI aseguran que la documentación se mantenga sincronizada con la implementación.

/**
 * Creates a new user account and sends a verification email.
 *
 * @param input - User registration data
 * @returns The created user (without password hash)
 * @throws {ConflictError} If email is already registered
 * @throws {ValidationError} If input fails schema validation
 *
 * @example
 * const user = await createUser({
 *   email: 'dev@example.com',
 *   name: 'Jane Doe',
 *   password: 'securePassword123'
 * });
 */
async function createUser(input: CreateUserInput): Promise<User> {
  const existing = await db.user.findByEmail(input.email);
  if (existing) throw new ConflictError('Email already registered');
 
  const hashed = await hashPassword(input.password);
  const user = await db.user.create({ ...input, password: hashed });
 
  await emailService.sendVerification(user.email, user.verificationToken);
 
  const { password, ...safeUser } = user;
  return safeUser;
}

Las anotaciones @throws son especialmente valiosas: documentan el contrato de errores que quienes llaman a la función deben manejar. Omitirlas hace que tipos de error sin gestionar terminen llegando a los usuarios finales.

Mantener viva la documentación

La documentación se pudre más rápido que el código. La única defensa es hacer que la documentación forme parte del flujo de trabajo, no que sea una ocurrencia tardía.

Estrategias que funcionan:

• Los ADRs son obligatorios para cualquier decisión que afecte a más de un equipo
• Los cambios de README forman parte de la checklist del PR para cambios de infraestructura
• La documentación de la API generada se ejecuta en la CI: si la documentación falla, el build falla
• Revisión trimestral de la documentación: elimina todo lo que esté mal (una documentación desactualizada es peor que no tener documentación)

Estrategias que fallan:

• Los "sprints de documentación": el backlog es infinito y los resultados quedan obsoletos de inmediato
• Una wiki aparte mantenida por un "campeón de la documentación": un único punto de fallo
• Exigir comentarios en cada función: genera ruido, no señal

Conclusiones clave

1. Conoce el tipo de documento: tutoriales, guías prácticas, referencias y explicaciones sirven a lectores distintos
2. Los ADRs son la documentación de mayor impacto: capturan el porqué, no solo el qué
3. Los README necesitan un Quick Start que funcione: si la puesta en marcha tarda más de 10 minutos, la documentación ha fallado
4. Los comentarios explican el porqué, no el qué: el código ya muestra qué hace
5. Automatiza lo que puedas: la documentación de API generada y las verificaciones de CI evitan que la documentación se pudra
6. Elimina la documentación obsoleta: una documentación incorrecta es peor que ninguna documentación