Nuestro proyecto de conversión de documentos en curso tiene como objetivo hacer que nuestros documentos sean lo mejor posible: Un modelo de excelencia industrial. Estamos estudiando cuatro pilares de documentos diferentes para lograr este objetivo.El primero de estos pilares es dirección. Define lo que es calidad En la documentación, y responda las preguntas: ¿Qué hace que la documentación sea buena?
El principio que nos guía para hacer esto es simple: Una buena documentación satisface las necesidades de los usuarios. Estamos adoptando Marco del documento de Diátaxis Ayúdanos a poner en práctica este principio.
Nuestra direccion
El marco de Diátaxis es un enfoque ligero y pragmático que satisface las necesidades de los usuarios de una manera sistemática al especificar una estructura básica para los documentos técnicos. Proporciona estándares y métodos para guiarnos: es un mapa y una brújula.
dirección Es una buena metáfora de nuestro trabajo en documentación. Cuando va a un lugar determinado, necesita saber exactamente a dónde va, incluso si no necesariamente sabe exactamente cuál es el destino final.Si está mapeando nuevas áreas, es posible que ni siquiera tenga sí Un destino final. Cuando no puede planificar todo el viaje con anticipación, debe estar preparado para adaptarse al entorno cambiante y los descubrimientos a lo largo del camino.
Sin embargo, su dirección esperada debe ser clara. En cualquier momento, debe poder saber la dirección en la que está mirando y dónde se encuentra. Necesita saber qué se encuentra entre usted y su próximo punto en el camino, y necesita saber qué hacer para llegar allí.
Nuestra direccion es calidadEl marco de Diátaxis se convertirá en nuestro mapa y brújula, nuestros estándares y pautas para lograr la calidad de los documentos.
Cuatro tipos de archivos
Diátaxis ha identificado cuatro modos o tipos de documentos diferentes: Tutoriales, Manual de operaciones, Referirse a y expliqueCada uno corresponde a las distintas necesidades de los usuarios en distintos momentos del ciclo de interacción con los productos tecnológicos. Cada uno tiene su propio propósito y cada uno necesita su propia forma y estilo únicos; cada uno debe ser diferente de los demás.
Tutoriales
Un tutorial es una lección, De forma segura en manos del disertante.
A veces el usuario es aprender Utilice el producto o ciertos aspectos del producto. Poco a poco se familiarizan con él, comprenden lo que se siente al usarlo y lo que pueden hacer con él. Luego, deben explicar paso a paso a lo largo de una ruta de aprendizaje cuidadosamente construida bajo la guía del maestro. Al final, los alumnos completarán un ejercicio pequeño pero significativo, mostrarán sus esfuerzos con algunas cosas concretas y obtendrán una nueva comprensión, conocimiento y confianza que no tenían antes. Este es el propósito del tutorial.
El tutorial debería verse como una lección. Está obligado a proporcionar un aprendizaje exitoso. ExperienciaExplicarle cosas o mostrarle hechos no es una experiencia de aprendizaje.La única forma de aprender habilidades es a través de haciendo, Entonces el tutorial no contiene explicaciones ni hechos: solo contiene explicaciones sobre cosas Hacer, El lector aprenderá a través de él.
Manual de operaciones
Cómo guiar es una receta, Que muestra al lector cómo lograr ciertos objetivos.
Cuando el usuario es Lograr algo Están trabajando, aplicando sus conocimientos a tareas o problemas reales. Ahora deben mostrarles los pasos clave a seguir. Lo que necesitan es una guía de operación.
A diferencia de los tutoriales, la guía de funcionamiento no es responsable de proporcionar una experiencia de aprendizaje. No tiene la obligación de enseñar. Se puede suponer que el lector ha dominado la habilidad y familiaridad con la máquina, su funcionamiento, el lenguaje utilizado para hablar de ella, etc. Su deber es mostrar a los usuarios cómo lograr algo paso a paso.Esta es la obligación de las partes usuario Saber lo que quieren lograr y poder aplicar las pautas a las necesidades de su situación específica.
Referirse a
El material de referencia es descripción, Para proporcionar datos sobre el usuario que opera la máquina.
Las guías de funcionamiento y los tutoriales están relacionados con los pasos reales.Por otro lado, a veces los usuarios no necesitan saber qué hacer, pero Como va esto. Los usuarios en el trabajo deben encontrar información Respecto a la máquina que están usando. Necesitan hechos actualizados y fiables (especificaciones, descripciones, detalles de implementación); los encontrarán en las referencias.
La referencia es independiente de lo que alguien necesite. HacerEste no es un lugar para explicaciones u orientaciones. Su obligación es presentar los datos aburridos sobre la máquina de la manera más completa y confiable posible para que los usuarios puedan usarla de manera efectiva. La estructura o arquitectura del documento de referencia debe seguir la estructura o arquitectura de la máquina para que se pueda asignar una a otra.
explique
La explicación es discusión, Para aclarar un tema.
En algún momento, los usuarios pueden buscar mejores o más profundos comprender El producto y cómo funciona. Quieren verlo en contexto desde una perspectiva diferente; quieren responder preguntas sobre por qué las cosas son así. Hay explicaciones para satisfacer estas necesidades.
La responsabilidad de Explanation es ayudar a los usuarios a pasar de ser un simple conocimiento o familiaridad con el trabajo a tener una comprensión más profunda y amplia del mismo. Todo lo que ayude a lograr este objetivo se puede introducir de forma gratuita: ejemplos, comparaciones, diferentes perspectivas, historia, elecciones, etc. El comentario debe ser como sus amigos conocedores, compartiendo sus ideas con usted.
Un lugar para poner todo, todo está en su lugar.
La relación entre estos cuatro modos de documento le da a Diátaxis su estructura única.
Para cualquier documento dado, debe quedar claro qué tipo de documento es; siempre será uno de los cuatro tipos, y solo uno. Esto muestra lo que debe contener el documento.Igualmente importante, muestra No Pertenece a un documento específico y debe colocarse en otro lugar.
Sirve a autores y usuarios. Ayuda a los autores a colocar el contenido en el lugar correcto del documento y ayuda a los usuarios a encontrarlo.
un ejemplo
Suponga que está escribiendo alguna documentación de seguridad para el producto. Desea asegurarse de que todas las cosas importantes que sabe sobre seguridad estén incluidas en el documento.Bajo Diátaxis, en lugar de considerar lo general e indiferenciado Seguridad Asunto, sabrá que todo lo que escriba sobre seguridad pertenece a uno de los cuatro tipos de documentos.
Por lo tanto, si comienza por escribir un documento de referencia de seguridad, sabrá que debe hacer una declaración clara y sencilla de los hechos. explique Característica o función de seguridad, o pantalla Cómo usarlo -Aquellos que no pertenecen aquí.Ahí sí Su lugar: un lugar diferente. Si necesita estas cosas, también debe haber un tema de descripción de seguridad o una guía de operación de seguridad. Esto facilita inmediatamente la vida de los autores de documentos, que se dan cuenta de que las explicaciones y presentaciones también son importantes y deben incluirse, pero de lo contrario pueden tener dificultades para encontrar una manera de ordenar y estructurar todo este contenido.
Para los usuarios, siempre tienen un necesitar En cualquier momento, está claro dónde satisfacer esta necesidad. Cuando los usuarios necesitan encontrar algo, saben que lo encontrarán en las referencias. Cuando estén allí, no se distraerán con explicaciones o instrucciones sobre cómo hacer algo que no están buscando.
Por otro lado, cuando realmente quieran saber cómo hacer algo, encontrarán lo que necesitan en el manual, lo que también evita obligar al lector a elegir su propio camino a través de referencias o explicaciones para averiguar qué es lo que realmente necesita. Hacer.
Diátaxis en nuestro trabajo de documentación
La estructura Diátaxis actúa como mapa y brújula en el documento, y es una colección de herramientas que le permite moverse en la dirección correcta. En cualquier momento, proporcionará algunas preguntas para preguntar qué estamos escribiendo y qué debemos escribir, y orientación sobre cómo debemos hacerlo:
- ¿Nuestros usuarios necesitan Guía de acciónO ellos Necesita conocimiento?
- Son nuestros usuarios estudiando o En el trabajo?
Debido a que la estructura hace estas distinciones claras, es fácil ver cuando un componente de un documento se confunde con un formulario que pertenece a otro. El material de referencia que interrumpe la descripción de la máquina para mostrar cómo hacer algo, o un tutorial que interrumpe el propio curso para divagar y explicar son ejemplos típicos de documentación confusa y desordenada. Diátaxis muestra cómo se equivocaron y Por qué Salieron mal de una manera que es fácil de asimilar.
Como lente, Diátaxis es despiadado. Cuanto más a fondo se adopta la estructura, más despiadadamente expone lagunas, errores y confusión.
Esto naturalmente significa que lo primero que hace Diátaxis es hacer que los documentos existentes se vean peor, no mejor: los problemas son más difíciles de ocultar e ignorar, y las cosas en el lugar equivocado inevitablemente se destacan. Pero así debe ser, porque si no puedes verlo claramente en primer lugar, no podrás resolver ningún problema.
En especificación
Estamos implementando este marco en nuestra documentación técnica, reorganizando los materiales existentes y usándolo para guiar la creación de nuevo contenido.Este trabajo se está realizando en las propiedades de nuestro documento; puede verlo en varias de estas propiedades, incluidas Nube de Anbox, Encantador Kubeflow, Esta Gerente de ciclo de vida del operador de Juju, Esta El encanto de OpenStack Guía, núcleo de Ubuntu.
En cada caso, verá la división de alto nivel de los documentos técnicos en cuatro tipos, con señales claras para que pueda encontrar claramente qué tipo de material y dónde encontrarlo.
Como se mencionó anteriormente, Diátaxis tiene el efecto secundario de resaltar problemas en el documento, y ya podemos verlos más claramente donde se aplica Diátaxis. Hacerlo público solo ayudará a acelerar el proceso de mejora.
El resultado final de nuestro proyecto será la documentación de nuestros productos y servicios. Estos documentos comparten una estructura común, y estas estructuras en sí mismas son más fáciles de navegar para encontrar lo que necesita.
Qué significa esto para usted
Se trata de Uds, Como alguien que recurre a nuestra documentación cuando usa nuestro software, porque necesita algo. Esto significa que nuestra documentación se basará en sus necesidades y se redactará para satisfacerlas.
En nuestra documentación, debería poder encontrar lo que espera Donde Espera que aparezca en una forma que cumpla con sus expectativas. Como lector, no tiene que hacer un trabajo adicional para descubrir o recordar dónde colocar el contenido que necesita. No debería verse obligado a cambiar su forma de pensar, porque el contenido que está leyendo ha cambiado de modo a la mitad. No debe distraerse con contenido irrelevante. Y nunca debe perder el tiempo buscando lo que necesita.Si no existe, debería ser obviamente No está allí, porque puede que solo tenga un lugar.
En definitiva, pondremos tus necesidades en nuestros documentos para que puedas lograr un mayor éxito con el software que creamos. Llevará tiempo, pero estamos comprometidos a cumplir esta promesa.
