Diátaxis: el marco de las ayudas

Todo el rediseño de las ayudas de Casiopea se ordena con Diátaxis, un marco para escribir y organizar documentación técnica creado por Daniele Procida y publicado en diataxis.fr. Este documento explica qué es, cómo se lee su mapa, cómo se usa su brújula y cómo se aplica en lo que muestra este sitio.

Qué es Diátaxis

Diátaxis parte de una observación: quien lee documentación no siempre necesita lo mismo. A veces quiere aprender algo desde cero; otras veces tiene una tarea concreta, busca un dato exacto o quiere entender por qué algo funciona así. Según el autor, hay cuatro tipos de documentación porque hay cuatro necesidades distintas, y cada tipo debe escribirse y organizarse de manera diferente (Start here).

El nombre viene del griego antiguo: dia («a través») y taxis («ordenamiento»).

Los cuatro tipos, o modos, son:

• Tutorial: una lección. Enseña haciendo y lleva de la mano a quien empieza (Tutorials).
• Guía práctica (how-to): una serie de pasos para lograr un objetivo concreto. Supone que la persona ya sabe lo básico (How-to guides).
• Referencia: una descripción exacta y completa, para consultar mientras se trabaja (Reference).
• Explicación: un texto que da contexto y responde al «por qué» (Explanation).

El problema más común en la documentación es mezclar modos: un tutorial que se detiene a explicar teoría, o una referencia llena de instrucciones. Cada mezcla le sirve mal a ambas necesidades. Diátaxis propone separarlos y unirlos con enlaces.

El mapa: dos ejes y cuatro cuadrantes

El mapa de Diátaxis (The map) ordena los cuatro modos según dos preguntas:

• ¿Acción o conocimiento? Tutoriales y guías sirven para hacer; referencias y explicaciones sirven para saber.
• ¿Adquirir o aplicar? Tutoriales y explicaciones sirven mientras se estudia; guías y referencias sirven mientras se trabaja.

Cada modo ocupa el cuadrante donde se cruzan sus dos respuestas. Los modos vecinos comparten un eje, y por eso tienden a mezclarse: es justo lo que hay que vigilar al escribir.

Acción: hacerConocimiento: saberAdquirir: estudiarAplicar: trabajar

• Actuar · Estudiar

  Aprender Tutorial

  Responde a «¿Me enseñas a…?». Orientado al aprendizaje; su forma es una lección.

  12 ayudas de Casiopea (8 con estructura lista)

• Actuar · Trabajar

  Resolver Guía práctica

  Responde a «¿Cómo hago…?». Orientado a un objetivo; su forma es una serie de pasos.

  36 ayudas de Casiopea (25 con estructura lista)

• Saber · Estudiar

  Entender Explicación

  Responde a «¿Por qué…?». Orientado a la comprensión; su forma es un texto que da contexto.

  14 ayudas de Casiopea (12 con estructura lista)

• Saber · Trabajar

  Consultar Referencia

  Responde a «¿Qué es…?». Orientado a la información; su forma es una descripción exacta.

  37 ayudas de Casiopea (37 con estructura lista)

La brújula: cómo saber qué modo corresponde

La brújula (The compass) es la herramienta práctica del mapa. Sirve cuando no está claro qué modo corresponde a un texto, a una página o incluso a una sola oración. Se hacen las mismas dos preguntas y la combinación de respuestas indica el modo.

Pruébala con cualquier ayuda de Casiopea:

1. ¿El contenido sirve para actuar o para saber?

Actuar: dice qué hacer, paso a paso. Saber: da información o contexto.

2. ¿Se usa mientras se estudia o mientras se trabaja?

Estudiar: sirve para adquirir una habilidad. Trabajar: sirve para aplicarla en una tarea.

Elige una respuesta en cada pregunta para ver el modo.

Cómo se aplica en Casiopea

Nombres de los modos

En la wiki, los modos se muestran con verbos que dicen lo que la persona quiere hacer. El nombre técnico de Diátaxis queda en la documentación del proyecto.

No se creó una propiedad semántica nueva: el modo se deriva del Tipo de Documento que ya existe. El único valor nuevo es Explicación, aprobado el 9 de octubre de 2026.

Dónde se ve en este sitio

• Portada de ayudas del prototipo: la sección «¿Qué necesitas?» agrupa todas las ayudas por modo, con su frase.
• Marca de modo: cada ayuda lleva un sello con su modo y una forma propia (círculo, triángulo, cuadrado y rombo), para que el modo no dependa solo del color. Está documentada en el Espécimen.
• Ficha de cada ayuda: dice su modo y su peldaño hacia la autonomía (Aprender 1, Resolver 2, Consultar 3, Entender 4).
• Puentes entre modos: cada ayuda enlaza a sus vecinas de otros modos. Por ejemplo, Primeros pasos en Casiopea (Aprender) lleva a Solicitar una cuenta (Resolver) y a Qué es Casiopea (Entender). Así se respeta la regla de no mezclar: el tutorial no explica, pero enlaza a la explicación.
• Árbol e inventario: la regla «una página, una necesidad, un modo» decide qué se divide. Si una página actual responde a dos casillas de la brújula, se separa en dos ayudas. Ver Árbol completo de ayudas y Inventario y propuesta de ficha.

Ejemplos

Referencias

• Procida, D. Diátaxis: A systematic approach to technical documentation authoring. https://diataxis.fr/
• Procida, D. Start here. https://diataxis.fr/start-here/
• Procida, D. The map. https://diataxis.fr/map/
• Procida, D. The compass. https://diataxis.fr/compass/
• Procida, D. Tutorials · How-to guides · Reference · Explanation. https://diataxis.fr/tutorials/ · https://diataxis.fr/how-to-guides/ · https://diataxis.fr/reference/ · https://diataxis.fr/explanation/

Los textos de este documento son una síntesis propia en español; el marco, sus nombres y sus diagramas originales pertenecen a su autor.