Writing for
Good
Insights
En resumen
¿Alguna vez se ha preguntado cómo estructurar su documentación técnica para lograr la máxima claridad e impacto?
Diátaxis ofrece un enfoque sistemático de la comunicación técnica que garantiza que su contenido sea a la vez informativo y accesible. Este artículo ofrece una introducción básica a Diátaxis, explicando sus principios fundamentales y cómo pueden aplicarse a sus escritos.
Guiar a los principiantes:
Tutoriales de aprendizaje
- Los tutoriales son lecciones que guían al lector a través de una serie de pasos para completar un proyecto.
- Un buen tutorial debe mostrar a los alumnos que pueden tener éxito con el producto mediante acciones significativas y realizables.
- Los tutoriales son cruciales para convertir a los nuevos alumnos en usuarios de un producto.
- Para escribir un buen tutorial, es esencial permitir que el usuario aprenda haciendo. El objetivo es ayudar al alumno a empezar, no convertirlo en un experto.
- El tutorial debe ser repetible y funcionar para usuarios con diferentes niveles de habilidad y recursos. Debe centrarse en pasos concretos más que en conceptos abstractos.
- Las explicaciones deben reducirse al mínimo, proporcionando sólo lo necesario para completar el tutorial y evitando distracciones innecesarias.
- Las opciones y alternativas deben omitirse para mantener la atención en el objetivo principal del tutorial.
- El lenguaje del tutorial debe ser claro, directo y sin ambigüedades.
Soluciones paso a paso:
Elaboración de guías prácticas eficaces
- Las guías prácticas son instrucciones paso a paso que ayudan a los lectores a resolver problemas del mundo real y están orientadas a (objetivos y tareas).
- Una buena guía práctica debe describir una secuencia de acciones en orden lógico, partiendo de un punto de partida conocido y llegando a una conclusión específica y útil.
- El objetivo principal de una guía práctica es resolver un problema o realizar una tarea. Deben evitarse las explicaciones o conceptos superfluos; si es necesario, pueden enlazarse por separado.
- La elección de títulos claros y precisos para las guías prácticas es crucial, ya que ayuda a los usuarios a comprender rápidamente de qué trata la guía.
El recurso definitivo:
Diseño de referencias exhaustivas
- Las guías de referencia son descripciones técnicas de maquinaria y de su funcionamiento. Están orientadas a la información y sirven como fuentes autorizadas de verdad y certeza para los usuarios.
- El objetivo principal de una guía de referencia es describir el producto y sus componentes, como API, clases, funciones, y cómo utilizarlos eficazmente.
- El material de referencia debe ser conciso, directo y sin ambigüedades. Los usuarios lo consultan para obtener información precisa en lugar de leerlo como si fuera una narración.
- Las guías de referencia actúan como mapas, proporcionando información esencial sobre el funcionamiento interno del producto sin necesidad de que los usuarios lo exploren por sí mismos.
- El lenguaje de las guías de referencia es objetivo y enumera comandos, opciones, advertencias y limitaciones para ayudar a los usuarios a manejar la maquinaria con eficacia.
Inmersión profunda:
Fomentar la comprensión con explicaciones detalladas
- La explicación se centra en proporcionar una comprensión más profunda y amplia de un tema. Aborda los temas desde diversos ángulos y perspectivas.
- A diferencia de los tutoriales y las guías prácticas, la explicación no se refiere a acciones concretas del usuario, y difiere del material de referencia, que ofrece descripciones técnicas detalladas.
- La comprensión es un aspecto fundamental de cualquier oficio, y la explicación desempeña un papel vital a la hora de entretejer los conocimientos y la experiencia del profesional.
- Aunque la explicación no sea tan urgente como otras formas de documentación, es igualmente importante. Ayuda a los profesionales a asimilar y retener los conocimientos, por lo que es esencial para dominar un oficio.
Tutoriales vs guías prácticas
Tutoriales
Guías prácticas
Propósito
Los tutoriales se centran en enseñar a los principiantes a utilizar un producto o completar un proyecto. Su objetivo es crear una competencia básica en el uso de un producto mediante un aprendizaje práctico.
Las guías prácticas están orientadas a objetivos y proporcionan instrucciones paso a paso para ayudar a los usuarios a resolver problemas del mundo real.
Contenido
Los tutoriales hacen hincapié en aprender haciendo, proporcionando pasos prácticos para lograr un resultado específico. Se centran en “cómo hacerlo”.
Las guías prácticas proporcionan secuencias claras de acciones para resolver un problema. Priorizan la consecución de una tarea de forma eficiente.
Audiencia
Los tutoriales se dirigen a los nuevos alumnos y pretenden convertirlos en usuarios del producto.
Las guías prácticas se dirigen a usuarios que buscan resolver problemas concretos de forma eficaz.
Lenguaje
Los tutoriales utilizan un lenguaje claro, directo y sin ambigüedades para guiar a los usuarios a través de pasos concretos.
Las guías prácticas utilizan títulos claros y precisos para transmitir rápidamente el contenido de la guía.
Referencias vs explicaciones
Guías de referencias
Explicaciones
Propósito
Las guías de referencia son descripciones técnicas de los componentes de un producto y de cómo utilizarlos eficazmente. Sirven como fuentes autorizadas de información.
Las explicaciones proporcionan una comprensión más profunda y amplia de un tema, abordándolo desde diversos ángulos.
Contenido
Las guías de referencia son concisas y objetivas, con una lista de comandos, opciones, advertencias y limitaciones. Actúan como mapas del interior del producto.
Las explicaciones se centran en la comprensión en profundidad y pueden explorar temas desde múltiples perspectivas.
Audiencia
Las guías de referencia se consultan para obtener información precisa y específica sobre los componentes de un producto.
Las explicaciones se dirigen a los profesionales que buscan una comprensión global de un tema.
Lenguaje
Las guías de referencia utilizan un lenguaje objetivo para ofrecer información técnica clara.
Las explicaciones ofrecen una visión más amplia y pueden explorar diversos aspectos de un tema.
Cómo empezar con Diátaxis
- Comprender el enfoque pragmático: Comprenda que Diátaxis es una herramienta que le ayudará a mejorar la documentación para los usuarios y a hacer más accesible su creación y mantenimiento. Acérquese a ella de forma pragmática, centrándose en su aplicación práctica.
- Utilice Diátaxis como guía: Considere Diátaxis como una guía o un mapa, no como un plan estricto. Está diseñada para ayudarle a pensar y entender su documentación, evaluar sus problemas e identificar áreas de mejora.
- No se preocupe inicialmente por la estructura: Evite gastar demasiada energía intentando que la estructura de su documentación sea perfecta desde el principio. En su lugar, céntrese en mejorar el contenido basándose en los principios de la Diátaxis.
- Simplemente haga algo: Empiece eligiendo cualquier parte de su documentación, aunque sea al azar. Evalúela críticamente en función de las necesidades de los usuarios y de las normas de Diátaxis. Decida una mejora inmediata y aplíquela.
- Ciclo de mejora: Después de realizar una mejora, vuelva al principio del ciclo. Siga repitiendo el proceso, identificando y abordando continuamente los problemas de su documentación.
- Permita el desarrollo orgánico: Adopte la idea de un crecimiento orgánico bien formado para su documentación. En lugar de planificar y ejecutar rígidamente, deje que su documentación evolucione y se adapte de forma natural en función de las mejoras que realice a nivel celular (pequeños cambios individuales).
