Noticias

De camino a Diataxis | Ubuntu

Descubrimos el Diátaxis Framework a principios de este año. Estaba en nuestra hoja de ruta cambiar el documento MAAS a esta nueva y genial forma de explicar las cosas. En este ciclo planeamos hacerlo realidad.

Pensarías que sería obvio….

Diataxis es uno de esos Ideas. Una vez que lo ha visto, no puede entender por qué no todos crearon este sistema. Este marco divide la documentación en cuatro áreas:

  • Explicaciones
  • Instrucciones
  • Tutoriales
  • Material de referencia

Al escribir, no debes mezclar los cubos. Debería tomarse el tiempo para examinar el material usted mismo; sin duda, le ayudará a documentar mejor sus propios sistemas.

Ordenar la documentación de MAAS en estos grupos requiere algunos separadores claros. Actualmente estamos adoptando un enfoque liberal, pero esto es lo que se nos ocurrió hasta ahora:

  • Explicaciones suponga que el lector está familiarizado con términos técnicos comunes como «DHCP» o «Conexión de red». Estas secciones solo explican la terminología, funciones, usos y matices de MAAS.
  • Instrucciones Debería ser un poco más que pasos. Probamos un poco estas guías con MAAS 3.0 y descubrimos que es posible crearlas además escaso. Mantendremos una cantidad razonable de explicaciones compactas en estas secciones para que no tenga que consultarlas con demasiada frecuencia.
  • Tutoriales serán explicaciones completas para principiantes, probablemente con secciones detalladas donde puede omitir los temas más básicos si lo desea. Lo más probable es que se agreguen al enlace del tutorial que está separado de la documentación.
  • Material de referencia debería permitirnos aliviar muchas de las páginas más técnicas con listas y tablas largas y complicadas (piense, por ejemplo, en «scripts de puesta en marcha» y «tipos de energía»). Dado que la documentación es un medio con hipervínculos, es muy sencillo vincular los diversos detalles técnicos de una página de referencia con los otros tipos de material.

Además, también estamos planeando simplificar la columna de navegación en el lado izquierdo de la página de documentos. Nuestros principales problemas con esto son: (1) que los objetos en la navegación no son todos objetos; (2) que no son del mismo tipo de objetos; y (3) que las estructuras de navegación no son construcciones paralelas, lo que En realidad importante para encabezados y listas. Los lectores luchan por encontrar el contexto cuando agrupan cosas que no son paralelas, como:

  • Limpiar el garaje.
  • Hay correo en el mostrador con el que no debería hacer nada.
  • ¿Qué son todas esas cosas en la parte de atrás de la nevera?
  • La cena es a las ocho en casa de Suzie.

Y, sin embargo, con el tiempo, nuestro menú actual se ha convertido orgánicamente en esta lista de tareas pendientes. Es hora de arreglar eso.

Hablando de contexto

Al implementar Diátaxis, esperamos mejorar el flujo de documentación, que es solo otra forma de decir que no queremos seguir cambiando el contexto del lector. En este caso, el contexto se refiere específicamente a una mentalidad o nivel de concentración. Mucha documentación informática es terrible porque cambia el contexto del lector en todas partes.

Por ejemplo, si se concentra en seguir unos pocos pasos para crear una nueva máquina virtual e implementarla, se encuentra en lo que se denomina un contexto de puesta en marcha. No querrás tener que leer una explicación detallada de cómo funciona algo cuando solo alrededor del cinco por ciento de esa lectura en profundidad es importante para ti. Y no desea mostrar una larga lista o tabla de las cosas que hace podría que hacer. Lo que desea en este momento es una serie de pasos concretos que lo llevarán de A a B con una explicación suficiente para evitar que se tropiece con la configuración.

Por otro lado, cuando está en modo de lectura en profundidad, es posible que no esté sentado directamente en el sistema y es posible que desee probar cada operación antes de seguir leyendo. Este tipo de discusión es más de naturaleza tutorial. Del mismo modo si tu que hacer Si desea ver esta larga lista de parámetros, no debe evitar las explicaciones técnicas laberínticas de cuatro páginas de cada posible matiz con respecto a algo que podría estar relacionado con esos parámetros.

En otras palabras, si cambiamos su contexto con demasiada frecuencia, deje de leer e intente algo. Si eso no funciona, puede escanear el documento una o dos veces, pero muy pronto estará en nuestra página de discursos MAAS pidiendo a alguien que descifre todo por usted. No hay nada de malo en el discurso de MAAS: es un gran foro y, últimamente, a uno de los miembros de nuestro equipo siempre se le ha encomendado la tarea de patrullarlo como una prioridad absoluta. Pero alrededor del ochenta y cinco por ciento de sus necesidades de información debería se cumplen con la documentación.

Así que esto es lo último del mundo doc MAAS. Le invitamos a expresar sus opiniones sobre la estructura y el formato de la documentación.

Publicaciones relacionadas

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Botón volver arriba