- Partiendo de la premisa de que la documentación técnica debe cumplir roles distintos según la situación del usuario, Diátaxis es un enfoque que organiza en conjunto el contenido, la estructura y la forma
- Divide las necesidades del usuario en 4 categorías y las hace corresponder con los tipos de documento tutorials, how-to guides, technical reference, explanation
- Más que una simple tabla de clasificación, se acerca a un framework de diseño documental que aborda qué escribir, cómo escribirlo y dónde ubicarlo
- También facilita a autores y responsables de mantenimiento evaluar la calidad de la documentación, y tiene como ventajas ser ligero, intuitivo y no imponer una forma específica de implementación
- Como muestran los casos de Vonage, Gatsby y Cloudflare, puede usarse como un criterio práctico para equipos que buscan mejorar la capacidad de navegación y la estructura de la información en su documentación
Los 4 tipos de documentación que distingue Diátaxis
- Diátaxis es una forma de pensar y de ejecutar para crear y operar documentación técnica
- El punto de partida es comprender las necesidades de quien usa la documentación, y a partir de ahí se derivan principios sobre contenido, arquitectura y formato
- Las necesidades documentales y sus formatos se dividen en 4 categorías
-
tutorials
-
how-to guides
-
technical reference
- explanation
- La documentación misma también debe organizarse en torno a estas 4 necesidades, y Diátaxis aborda al mismo tiempo tres preguntas
- content: qué escribir
- style: cómo escribir
- architecture: cómo organizar
-
Aplicabilidad para autores y responsables de mantenimiento
- Diátaxis es un enfoque útil no solo para quienes usan la documentación, sino también para quienes la escriben y la mantienen
- Es ligero y fácil de entender
- Su aplicación es intuitiva
- No impone restricciones de implementación
- Proporciona principios de calidad para que quienes la mantienen puedan evaluar su propio trabajo
- Sus principios se resumen a partir de su adopción exitosa en cientos de proyectos de documentación
Casos reales de proyectos de documentación
- Greg Frileux, de Vonage, evaluó que con Diátaxis pudieron crear un conjunto de documentación interna que gusta a los usuarios y al que también les resulta fácil contribuir a los colaboradores
- Gatsby señaló que, al reorganizar su documentación open source, usó el framework Diátaxis como recurso principal, y que las 4 áreas ayudaron a priorizar los objetivos de los usuarios para cada tipo de documento
- Cloudflare tomó Diátaxis como referencia de arquitectura de la información en el rediseño de Cloudflare developer docs, y consultó el framework al decidir dónde debía ubicarse cada contenido nuevo
1 comentarios
Opiniones de Hacker News
Incluso desde la perspectiva de alguien que no escribe profesionalmente, más allá de los detalles, la idea más importante y básica que me llevé de esto es que no hace falta decir todo exactamente una sola vez.
Antes de toparme con esta idea, me enredaba pensando que un único flujo de texto tenía que cumplir el papel de “todo el documento”.
Solo darse cuenta de que se puede escribir la misma información de distintas maneras para distintos lectores ayuda muchísimo.
Como el lector termina buscando el denominador común entre los ejemplos, resulta menos ambiguo que explicarlo con un solo ejemplo.
Autores como Salomón en los Proverbios bíblicos también usan mucho esta técnica.
En el resumen escribes “este artículo evalúa Y con Z y muestra que X se cumple”; en la introducción explicas que el problema de A es importante por B, pero que se ha pasado por alto el aspecto X, y que al evaluar Y, a diferencia de Z, aparecen desafíos realistas; y luego rematas otra vez con “en resumen, por X, Y es mejor que Z”.
En el trabajo relacionado también sigues diciendo que el enfoque de Z mejoró algo, pero que no es suficiente, como se verá más adelante, y en cada sección terminas volviendo una y otra vez al mensaje central.
Hace dos semanas apliqué este framework a la documentación de Sequin, y solo tener una estructura ya fue muy bueno.
Ahora el flujo de la documentación es mucho mejor, y como sabemos dónde poner cada cosa, también es más fácil agregar y mantener documentos.
Eso sí, irónicamente, la propia documentación de Diátaxis es un poco difícil y larga; recién después de leerla varias veces le agarré la mano.
Cuando se lo expliqué al equipo, usé la analogía de comprar un utensilio de cocina como una olla a presión: primero ves en el inicio rápido (tutorial) más o menos cómo ir de A a B; luego buscas cómo preparar un plato específico que te gusta, que sería el how-to; si te surgen detalles, revisas en la referencia los tiempos exactos de cocción para cada tipo de frijol; y cuando quieres saber por qué la presión cambia el tiempo de cocción o cómo funciona el mecanismo de seguridad, lees el material explicativo.
Curiosamente, nuestra documentación estaba completamente al revés y empezaba con explicaciones como “How Sequin Works”.
El impulso natural de un ingeniero es explicar primero cómo funciona y por qué se construyó así, para instalar un modelo mental, pero la gente no tiene ese tiempo ni esa paciencia.
Es mejor adaptar a los usuarios a la visión del mundo con el flujo inicio rápido → how-to → referencia, y recién después de haber conseguido verdadero interés, convencerlos del enfoque con material explicativo.
https://sequinstream.com/docs
Muchas veces la documentación se vuelve vaga con tonterías como “experiencia de sinergia innovadora”, como si a la empresa le diera vergüenza admitir que su herramienta es simplemente una herramienta, o al contrario, entra en detalles demasiado específicos antes de abordar “por qué existe este producto”.
Eso sí, en la documentación aparece repetidamente CDC, y tuve que buscar su definición. He implementado CDC varias veces en mi carrera, pero no estaba familiarizado con la sigla.
Al final, el flujo es elección del lector; mi cabeza funciona queriendo primero una explicación completa, y después buscando how-tos y tutoriales.
Desde el punto de vista de un redactor técnico, Diátaxis se parece a DITA: https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/information-typing.html
Sin embargo, estos sistemas pueden pasar por alto lo que los usuarios realmente necesitan.
Si la documentación técnica se usa solo dentro de una plataforma de documentación, Diátaxis puede encajar bien durante mucho tiempo, pero si la misma información puede y debe usarse en varios lugares, como la UI, un portal de documentación o una app móvil, quizá haya que dividir la información en piezas más pequeñas y ensamblarla de distintas maneras.
A esto se le llama reutilización de contenido, y consiste en usar el mismo contenido en varios lugares.
Uno de los enfoques para escribir y editar información orientada a la reutilización de contenido se explica en el concepto “every page is page one”: https://everypageispageone.com/the-book/
Si tienes recursos y tiempo, recomiendo hacer investigación UX al inicio del proyecto. Así se puede evitar que más adelante un modelo de información demasiado restrictivo termine asfixiando el trabajo.
Nielsen/Norman también ha investigado mucho esta área y propone ideas interesantes para resolver problemas relacionados: https://www.nngroup.com/articles/information-foraging/#toc-what-is-information-foraging-2
DITA distingue tipos de tema como tarea, referencia y concepto, pero los tutoriales o las guías de solución son una combinación de esos tipos de tema.
Aquí parece que el foco está en entregables más grandes que los temas individuales.
También me pregunto si, estando tan metidos en DITA, la complejidad no se vuelve un problema.
Si se divide el contenido en fragmentos reutilizables y se marca con semántica de DITA o DocBook, parecería que a los modelos grandes de lenguaje les resultaría mucho más fácil “entenderlo”, pero no he visto datos al respecto.
Hoy hay mejores formas de escribir documentación que pelearse con XSL/FO y sus parientes.
En el ámbito de la redacción de documentación técnica, ya es muy popular y está bastante cerca de ser un estándar.
Sin embargo, a veces se lleva demasiado lejos y se dejan literalmente solo esas cuatro categorías en la página de documentación, y eso por lo general no funciona bien.
Principalmente resulta útil para que quien escribe mantenga una idea como “esto es una guía, así que no intentemos enseñar; enfoquémonos en llegar al resultado”.
En la práctica, no conviene tener límites demasiado rígidos, y está bien que una guía incluya un poco de tutorial.
Creo que el punto donde este enfoque realmente se atasca es cuando falta conexión entre los cuadrantes.
Por ejemplo, en un framework de software, si una guía no enlaza al material de referencia de una clase o método específico que finalmente habrá que usar, se vuelve mucho más difícil explorar el contexto alrededor.
Algunos documentos de frameworks concretos dividieron los cuadrantes de esta forma, y una de las mayores molestias de esos documentos es precisamente esa.
Si no hay otros expertos, para un principiante puede ser mejor seguir las reglas estrictamente que “intentar hacer lo correcto por su cuenta”.
Por definición, el principiante no tiene la experiencia necesaria para hacer ese juicio, y a medida que gana experiencia empieza a ver en qué puntos debe apartarse de las reglas establecidas.
Es parecido a la diferencia entre cocinar en casa siguiendo un recetario y que un chef profesional eche ingredientes a la olla por intuición y sabor.
Pero trabajé con alguien que sostenía que en un tutorial no debería haber ni una sola frase explicativa, y que las reglas debían seguirse al pie de la letra.
Ahí está precisamente el riesgo de este tipo de sistemas.
Es parecido a principios de programación como “no modifiques variables globales” o “mantén las funciones cortas”.
No hace falta cumplirlos a la perfección, pero en la mayoría de los casos es mejor moverse más en esa dirección que en la contraria.
Así que le pedí a Claude que clasificara la sección superior según Diátaxis, y respondió que era principalmente explicación con algunos elementos de referencia mezclados, y que no era ideal según los criterios de Diátaxis.
Dijo que sería mejor dividirla en una sección que explicara puramente el concepto y la importancia del ajuste de hiperparámetros, y otra sección de referencia separada que enumerara las herramientas y métodos disponibles.
Pero luego también resumió por qué este enfoque integrado funciona bien en el contexto de una guía de usuario: sigue el flujo en que la gente realmente aprende, conecta de inmediato los conceptos con la implementación, revela gradualmente desde los conceptos básicos hasta herramientas complejas, y aporta valor práctico al unir teoría y práctica.
Como alguien que acaba de lanzar su primera app con SwiftUI, siento con fuerza que en la industria tecnológica moderna la documentación se trata con demasiada ligereza.
Extraño muchísimo el trabajo de los excelentes redactores técnicos que Apple despidió, y los ingenieros de Apple escriben documentación realmente mal.
Aun así, siempre soy cauteloso con los enfoques “dogmáticos”. Es fácil que surja una “clase sacerdotal” que no cede aunque la realidad lo exija.
Quienes crearon originalmente esa doctrina la aprovechan muy bien, pero los “sacerdotes” que vienen después la arruinan y convierten el enfoque en una maldición.
Muchas buenas ideas se han arruinado por una aplicación excesivamente rígida. Basta ver en qué se convirtió “Agile”.
La documentación tiene básicamente dos caras: mantenedores y usuarios, y como sus necesidades son muy distintas, quizá deberían encargarse de ellas equipos completamente diferentes.
También está el problema de que la documentación en varios lugares se desincroniza, pero lo importante es el resultado.
Si se pueden sincronizar eficazmente varias instancias, la documentación es efectiva y útil para el consumidor.
Incluso una documentación perfectamente formateada y sincronizada no tiene valor si nadie la lee.
En SNL, The Anal-Retentive Chef, interpretado por Phil Hartman, pasaba tanto tiempo preparando todo que no alcanzaba a hacer la demostración de cocina real, y veo mucho de eso en tecnología.
A veces la cadena de herramientas y las bibliotecas son perfectas, pero en la práctica no se pueden usar.
La documentación es una mezcla de varias disciplinas: naturaleza humana y psicología, diseño gráfico, arquitectura de la información, infraestructura técnica, publicación y distribución.
En la mayoría de los proyectos, la documentación se trata como algo para después, pero creo que debería ser una consideración de primera clase desde la etapa de requisitos.
Se puede profundizar indefinidamente en la estructura de la documentación, pero hasta que se encuentren los puntos donde hace agua, funciona como excelentes rueditas de apoyo.
Suena como si el malentendido común o la mala aplicación de una buena idea arruinara la idea en sí.
Más bien, hay experiencia que ganar en la aplicación real. Si la idea inicial en realidad no era buena, eso rompe la ilusión; y los malos ejemplos, si se interpretan mal, revelan ambigüedades que llevan al fracaso y permiten refinar la idea.
Eso sí, si mucha gente se acostumbra a malas implementaciones, la popularidad de la idea puede disminuir y también la demanda de implementaciones más refinadas.
Eso se parece más a una tragedia de los anticomunes que a una degradación de la idea en sí.
Diátaxis es excelente para estructurar documentación, pero su verdadero valor está en que simplifica la forma de escribirla.
Ayuda a salir de la idea de meter todo en un único “documento perfecto” y a reconocer que distintos usuarios tienen distintas necesidades.
Los tutoriales son para aprender siguiendo pasos, las guías son para resolver problemas concretos, las referencias son para consultas rápidas y las explicaciones profundizan en el “por qué”.
Esa claridad por sí sola puede llevar a escribir documentación útil.
Pero cualquier sistema, si se sostiene con demasiada rigidez, se convierte en una trampa.
O me pregunto si existe un paradigma unificado.
En nuestra organización usamos este método, y desde que lo adoptamos la documentación técnica pasó a otro nivel.
Sumado a la propiedad de página y a revisiones periódicas por parte de cada responsable de página, se convirtió en el único trabajo de documentación técnica exitoso que he visto.
Creo que la imagen que usa Divio es mucho más intuitiva: https://docs.divio.com/documentation-system/
Aunque parece que Diátaxis documenta cada significado de forma más completa.
La versión reescrita de Divio en Diataxis.fr tiene gráficos menos recargados, pero en esencia me parece igual a la que usaba Divio.
Siempre he considerado ambos recursos como prácticamente el mismo documento en cuanto a la idea que presentan dentro del contexto de sus respectivos sitios web.
Me gustaría saber qué aspecto te parece más intuitivo.
Me gusta esta idea y tuve la suerte de conocer a su creador un par de veces en PyConUK. Es una persona talentosa y muy amable.
Dicho eso, tengo mis reservas sobre separar con tanta rigidez las distintas áreas de la documentación.
En un sprint, alguna vez me dijeron que una documentación que estaba preparando no era aceptable porque mezclaba varios formatos. Para que quede claro, no fue Daniele quien lo dijo.
No quiero apelar a la autoridad, pero trabajé como docente por más de 20 años y tengo cierta intuición sobre cómo explicar y andamiar el aprendizaje para que la gente pueda hacer el trabajo y, al mismo tiempo, construir comprensión.
Mientras no haya una rigidez absoluta, esto es una excelente herramienta para decidir cómo crear documentación y qué debería hacer cada tipo de documento.
A menudo veo, por ejemplo en numpy, casos en los que los ejemplos podrían elegirse mucho mejor en vez de usar ejemplos tipo “magia caída del cielo”.
Un solo ejemplo bien elegido puede mostrar el uso y, a la vez, aportar mucho aprendizaje sobre casos límite o puntos a tener en cuenta.
En teoría creo que es correcto, pero me cuesta estar de acuerdo. Las palabras son demasiado cercanas.
Para mí, “tutorial”, “guía práctica” y “explicación” se sienten, en la práctica, casi como sinónimos.
Si lo pienso a fondo, entiendo que cada categoría tiene una razón de ser, pero semánticamente están tan cerca que mi cerebro no ve la diferencia.
Cuando quiero saber cómo funciona algo y veo “tutorial” y “guía práctica”, no sé en cuál hacer clic y termino haciendo clic en el primero.
Buscar términos que te funcionen mejor puede ser un ejercicio útil.
O también puedes entenderlo como la distinción entre acción/cognición, es decir, “hacer vs. pensar”, y adquisición/aplicación, es decir, “en aprendizaje vs. en el trabajo”.
También hay una página dedicada a distinguir tutoriales y guías prácticas: https://diataxis.fr/tutorials-how-to/
Una de las distinciones más simples es que un tutorial es algo que no puedes hacer en Stack Overflow.
Un tutorial sigue un plan de clase definido por un docente y va llenando huecos que el estudiante ni siquiera sabe que tiene.
En Stack Overflow tienes que hacer una pregunta, pero un tutorial es material para alguien que todavía ni siquiera sabe qué preguntar.
Hay muchas preguntas populares sobre cómo hacer tareas simples, pero para encajar en ese formato tienes que formular una pregunta, no pedir ayuda de forma vaga: https://meta.stackoverflow.com/questions/284236
La documentación de Diátaxis explica la diferencia con bastante eficiencia: un tutorial es una experiencia orientada al aprendizaje; una guía práctica, instrucciones orientadas a un objetivo; una referencia, una descripción técnica orientada a la información; y una explicación, una discusión orientada a la comprensión.
En este sistema, “tutorial” debe leerse como un término técnico, no como una palabra de uso cotidiano.
Es parecido a cuando un psicólogo dice “depression”: no significa exactamente lo mismo que en el uso cotidiano.
Aun así, es mejor que llamarlos tutoriales Tipo I-IV.
Una clase es una explicación, y un tutorial o una práctica es una experiencia guiada; me recuerda a Contoso, la empresa ficticia de Microsoft.
Una guía práctica es lo que necesitas cuando buscas una solución o le preguntas a ChatGPT, y una referencia es algo como un diccionario de sinónimos, una enciclopedia o un manual de usuario.
Los videojuegos tienen tutoriales incorporados, pero para los acertijos difíciles sigues necesitando una guía, y la configuración de teclas la consultas en la referencia.