Diátaxis – un enfoque sistemático para la redacción de documentación técnica

• Diátaxis es un concepto que propone un enfoque sistemático para la redacción de documentación técnica. Este enfoque parte de una aproximación estructurada para entender las necesidades de quienes usan la documentación, y propone una manera de abordar el contenido, la estructura y el formato.
• Diátaxis, derivado del griego antiguo, identifica cuatro necesidades claras y los formatos documentales correspondientes: tutoriales, guías prácticas, referencia técnica y explicación. Propone organizar la documentación de acuerdo con la estructura de estas necesidades.
• Diátaxis resuelve problemas relacionados con el contenido de la documentación (qué escribir), el estilo (cómo escribirlo) y la estructura (cómo organizarlo).
• Tiene valor no solo para quienes usan la documentación, sino también para quienes la escriben y la mantienen. Es ligero, fácil de entender y simple de aplicar. No impone restricciones de implementación y ofrece principios proactivos para mejorar la calidad de la documentación.

Contenido

• Este sitio web se divide en dos secciones principales que ayudan a aplicar y comprender Diátaxis.

  • Empieza aquí. Estas páginas ayudan a entender el enfoque de forma inmediata y concreta.
    • Aplicar Diátaxis
    • Tutoriales
    • Guías prácticas
    • Referencia
    • Explicación
    • Brújula
    • Flujo de trabajo
  • Esta sección explora con mayor profundidad la teoría y los principios de Diátaxis, y presenta una comprensión de las necesidades que lo sustentan.
    • Entender Diátaxis
    • Fundamentos
    • Mapa
    • Calidad
    • Tutoriales y guías prácticas
    • Referencia y explicación
    • Jerarquías complejas

• Diátaxis es un principio probado en la práctica. Ha sido adoptado con éxito en cientos de proyectos de documentación.

  • En Gatsby, al reorganizar la documentación de código abierto, usaron el framework Diátaxis como recurso principal. Sus cuatro cuadrantes ayudan a priorizar los objetivos de la persona usuaria para cada tipo de documentación.
  • Al rediseñar la documentación para desarrolladores de Cloudflare, Diátaxis se convirtió en la estrella polar de la arquitectura de la información. Al consultar el framework para decidir dónde ubicar contenido nuevo, la documentación se volvió más clara tanto para lectores como para colaboradores.

[GN⁺]

Comentarios de Hacker News

• Un usuario menciona que es importante darse cuenta de que no es necesario transmitir toda la información de una sola vez. Dice que es útil redactar la información de distintas maneras para diferentes lectores

• Explica que al aplicar el framework Diátaxis a la documentación de Sequin, mejoró el flujo de la documentación. Sin embargo, menciona que la documentación de Diátaxis en sí es algo difícil de entender y extensa

  • Lo explica con la analogía del proceso de comprar utensilios de cocina
    • Primero, mediante un tutorial de "inicio rápido", se revisa el uso general
    • Averiguar cómo usarlo para una receta específica sería el "how-to"
    • Si se quiere saber más a fondo, se buscan materiales de referencia
    • Si se quiere entender el principio científico de la cocción a presión, se leen materiales explicativos

• Redactores de documentación técnica mencionan que Diátaxis es similar a DITA. Sin embargo, explican que puede pasar por alto las necesidades del usuario y que, para reutilizar información, es necesario dividirla en fragmentos pequeños

• Un usuario que desarrolló una app con SwiftUI siente que la documentación técnica moderna suele tratarse de forma deficiente y sostiene que la documentación debe considerar tanto la perspectiva de quienes la mantienen como la de quienes la usan

• Se menciona que Diátaxis es útil para estructurar documentación, pero que aplicarlo de manera demasiado estricta puede convertirse en una trampa

• Se explica que el verdadero valor de Diátaxis está en simplificar la forma de redactar documentación. Es importante escribir la documentación de acuerdo con las necesidades de cada usuario

• Se menciona que el gráfico de divio es más intuitivo, pero que Diátaxis ofrece una documentación más completa

• Se explica que, tras adoptar Diátaxis, la documentación técnica mejoró mucho, y que la propiedad de las páginas y las revisiones periódicas contribuyeron a una documentación exitosa

• Se menciona que el framework Diátaxis ofrece una estructura simple y fácil de entender, por lo que resulta útil para redactar documentación técnica

• Se está redactando la documentación de Logdy con Diátaxis y se pide opinión sobre si este método es útil para documentar productos de software. Se explica que, mediante publicaciones de blog, se logró transmitir de forma efectiva cómo usar el producto