Diátaxis: el framework que usa Cloudflare para documentar y que la mayoría de devs ignora

Tu proyecto tiene 10,000 estrellas en GitHub y nadie lo usa. Suena cruel, pero casi siempre hay un culpable: documentación que apesta. Y no es tu culpa: nadie te enseñó a documentar. Hasta hoy.

Un framework llamado Diátaxis explotó en Hacker News con 427 puntos y 50 comentarios en horas, y no es una librería nueva ni un modelo de IA. Es un sistema para escribir documentación que ya usan Cloudflare, Gatsby y Vonage. Y el 90% de los desarrolladores ni siquiera sabe que existe.

¿Qué es Diátaxis? (y por qué el nombre suena a fármaco griego)

Diátaxis viene del griego dia ("a través") y taxis ("orden"). Lo creó Daniele Procida, y su tesis es brutalmente simple: la documentación tiene 4 necesidades distintas de usuario, y mezclarlas es el error que mata proyectos.

No es un generador de docs, no es una plantilla, no te obliga a migrar a nada. Es una forma de pensar que resuelve tres problemas: qué escribir, cómo escribirlo y cómo organizarlo.

Lo más poderoso: no impone ninguna herramienta. Lo aplicas en READMEs, en wikis, en docs de MkDocs, en lo que ya tengas.

Los 4 cuadrantes que lo cambian todo 🧭

Diátaxis divide toda documentación en cuatro tipos. Si no sabes cuál estás escribiendo, estás escribiendo mal:

📗 Tutoriales: aprendizaje orientado. "Haz tu primera app". El lector quiere aprender, no resolver un problema puntual.

📘 Guías how-to: orientadas a tareas. "Configura autenticación". El lector ya sabe qué quiere hacer: resolver un problema específico.

📙 Referencia técnica: orientada a información. "Todas las opciones de la API". El lector busca un dato exacto, rápido, sin rodeos.

📕 Explicación: orientada a comprensión. "Cómo funciona la arquitectura por dentro". El lector quiere entender, no ejecutar nada.

¿Ves el patrón? Cada cuadrante responde una pregunta distinta: quiero aprender, quiero hacer, quiero consultar, quiero comprender. Mezclarlos produce esa documentación eterna donde no encuentras nada.

El error que comete el 90% de los proyectos 💀

La mayoría de los repos tiene un README gigante que intenta ser tutorial + how-to + referencia + explicación al mismo tiempo. Resultado: un muro de texto que nadie lee.

Adam Schwartz, de Cloudflare, lo resume así: "Diátaxis se convirtió en nuestra estrella polar para la arquitectura de información. Cuando no sabíamos dónde debería ir un contenido, consultábamos el framework".

Gatsby reorganizó toda su documentación open source con los cuatro cuadrantes: "Los cuatro cuadrantes nos ayudaron a priorizar el objetivo del usuario para cada tipo de documentación", dice Megan Sullivan. Vonage construyó docs internas que sus contribuidores aman actualizar — algo casi tan raro como un unicornio.

Por qué esto te importa aunque no escribas docs 🚨

Aquí va la parte incómoda: la documentación es el producto. Una API sin docs es una API que no existe. Un proyecto open source sin docs claras no consigue contribuidores. Una librería sin ejemplos no consigue adopción.

Un estudio tras otro lo confirma: el 80% de los usuarios abandona un producto técnico si la documentación es confusa. No abandonan porque tu código sea malo: abandonan porque no pudieron entenderlo.

Y ojo, esto golpea más fuerte en LATAM: cuando la doc está en inglés técnico denso, sin ejemplos claros, el usuario latino se rinde el doble de rápido. Documentar bien no es un lujo: es tu estrategia de adopción.

Cómo aplicarlo hoy, en 10 minutos ⏱️

No necesitas releer 400 páginas. Haz esto ahora mismo:

1️⃣ Abre tu README o tu wiki y clasifica cada sección en uno de los cuatro tipos.

2️⃣ Sepáralas: un archivo o sección para tutoriales, otra para how-tos, otra para referencia, otra para explicación.

3️⃣ Regla de oro: si un párrafo no responde claramente a una sola de las 4 necesidades, reescríbelo o muévelo.

4️⃣ Pon el tutorial al principio. La gente aprende haciendo, no leyendo specs.

Eso es todo. Diátaxis es ligero, se entiende en 5 minutos y mejora la documentación sin tocar una sola línea de tu stack.

Mi opinión polémica 🔥

La industria gastó billones en frameworks, compiladores y herramientas de IA, pero sigue documentando como en 1998. Diátaxis lleva años probado en producción — no es teoría de universidad — y recién ahora está explotando en portada de HN.

Eso dice mucho: preferimos escribir código nuevo antes que explicar el que ya escribimos. Y es exactamente por eso que tu proyecto tiene 10,000 estrellas y nadie lo usa.

La documentación no es el afterthought del desarrollo: es el embudo de adopción. Aprende Diátaxis, aplícalo esta semana, y mira cómo cambia la conversación con tus usuarios.

Comparte esto con ese compañero que mete todo en un README de 3,000 líneas. Se lo debes. 🤝

¿Y tú? ¿Cómo está de caótica tu documentación actual — README monolito o ya separas los 4 tipos? Cuéntamelo en los comentarios. 👇