Documentación como Producto: El README que nadie lee
Tratar docs con el mismo rigor que el código: estructura, audiencias, ejemplos ejecutables y métricas de fricción (menos reuniones, más claridad).
Todo equipo ha escuchado “está en el README” mientras alguien comparte pantalla otra vez. No es que la gente odie leer: es que el documento no es un producto usable. Un README mal estructurado —sin objetivo, sin pasos ordenados, sin troubleshooting— empuja a la gente al canal de chat. La documentación efectiva reduce reuniones, acelera onboarding y hace que la arquitectura sea visible sin heroísmo individual.
Tipos de documentación (inspirado en Diátaxis)
- Tutoriales: llevan al lector a un primer éxito guiado paso a paso.
- How-to: resuelven una tarea concreta (“cómo rotar secretos”).
- Referencia: precisa, exhaustiva, sin narrativa larga.
- Explicación: el “por qué” de decisiones de arquitectura (ADRs enlazados).
README mínimo que sí se lee
# Servicio de facturación
## Qué hace (1 párrafo)
## Requisitos (versiones exactas)
## Quickstart
1. cp .env.example .env
2. pnpm install
3. pnpm dev
## Troubleshooting
- Error A → causa → fix
## Arquitectura (diagrama + ADR-001)
## Contacto/on-callMétricas de fricción (informales pero útiles)
Cuenta cuántas veces la misma pregunta aparece en Slack tras un onboarding. Si baja semana a semana, tu documentación está funcionando como producto. Si no, no es “pereza de lectura”: es señal de que hay que iterar el doc — igual que iterarías una pantalla con mala conversión.
SEO interno y externo
Para el mundo: artículos públicos con palabras clave honestas atraen talento y clientes. Para el equipo: buscabilidad en el repo (títulos claros, índice en `/docs`) ahorra vida. La documentación es el interfaz de tu sistema social: si es confusa, el sistema social compensa con reuniones — caras para todos.
Plantillas vivas: documentación que se prueba en CI
Donde sea posible, convierte ejemplos en tests o scripts verificados: snippets que se ejecutan en pipelines para asegurar que no se pudren. Un README cuyo “quickstart” falla cada dos semanas es peor que no tener README: destruye confianza. La documentación como producto implica versionado y ownership igual que el código.
Finalmente, celebra cuando alguien nueva/o llega y no pregunta lo mismo dos veces: significa que iteraste bien. Esa es la métrica oculta del éxito documental — y tiene un impacto directo en la velocidad del equipo y en la satisfacción de quienes odian depender del “conocimiento tribal”.
Artículos relacionados
Documentación de Arquitectura que Sí se Actualiza
Plantillas, ownership y rituales para que la documentación técnica no se vuelva obsoleta al mes.
DX para Plugins Internos y Herramientas de Equipo
Buenas prácticas para construir herramientas internas que realmente adopte el equipo.
Cultura de Postmortems sin Culpas y con Aprendizaje Real
Cómo convertir incidentes en mejoras sistémicas en vez de buscar culpables.