Approaches to writing good documentation / Estrategías para escribir buena documentación

[jaimev]

This is a new topic where we can compile collect and organize any references we find that might help guide us on our path to improving our technical documentation.

---

Este es un nuevo hilo en el que podemos recopilar y organizar todas las referencias que encontremos y que puedan servirnos de guía en nuestro camino para mejorar nuestra documentación técnica.

---

User research
Identifying Readers Documentation readers are not just users.
Contact Readers one-on-one interviews with people you already know, short survey for a wider audience
Use cases and user emotional state Users are either learning a new product, learning a new feature , or troubleshooting

Prioritizing what documentation is needed
User Task Analysis Make a table to identify what documentation items would be common to different user types
Gap Analysis Make a table evaluating “value” vs “effort” of pending documentation items
JIT-What is worth documenting Map the intersection between what users want, what the system can do, and what users can’t figure out

Evaluating existing documentation
Content Map Make a spreadsheet of current nagivation hierarchy
Content Audit Flag old documentation as redundant, outdated or trivial and score effort needed to improve it

Approaches to writing documentation
Start with what the reader needs
Fast thinking vs Slow thinking

Documentation Types
Diátaxis Framework - There are four modes of documentation - tutorials, how-to guides, technical reference and explanation.
DITA data model - There 3 types of documentation, concepts, tasks and reference.
JIT-Documentation Types - Respond to 4 types of questions: where is it?, how do i?, what the hell?, is there another way?

Information Architecture and Navigation
Card Sorting Category planning excercise
Tree Testing Category testing excercise
Non hierachical navigation Search, discovery, leading to related content

Project management
Good enough planning - a good plan now is better than a perfect plan next week
Never finished - Always complete Be like a frog
Workflow Cycle evaluate, prioritize, research, write, review, publish, get feedback, and start again at evaluation
Just in Time Documentation create just enough documentation just in time
Maturity Models - define project maturity stages, track your progress towards goals over time

More Resources
Write the Docs - Learning Resources - Resources compiled by Write the Docs community.
Write the Docs - Guide - An list of small guides on specific topics related to documentation.

---

Investigación de usuarios
Identificación de lectores Personas lectores de documentación no solamente son usuarios.
Contactar a lectores entrevistas individuales con personas que ya conoces, breve encuesta para un público más amplio
Casos de uso y estado emocional del usuario usuarios están aprendiendo un nuevo producto, aprendiendo una nueva característica , o solucionando problemas

Priorizar la documentación necesaria.
Análisis de las tareas del usuario Haz una tabla para identificar qué elementos de la documentación serían comunes a los diferentes tipos de usuarios
Análisis de las diferencias Haga una tabla para evaluar el “valor” frente al “esfuerzo” de los elementos de documentación pendientes
JIT-¿Qué vale la pena documentar? Haz un mapa de la intersección entre lo que los usuarios quieren, lo que el sistema puede hacer y lo que los usuarios no pueden resolver

Evaluación de la documentación existente
Mapa de contenidos Haz una hoja de cálculo de la jerarquía de navegación actual
Auditoría de contenidos Marcar la documentación antigua como redundante, obsoleta o trivial y calificar el esfuerzo necesario para mejorarla

Enfoques para la redacción de la documentación
Empezar por lo que necesita tu lector
Pensamiento rápido o lento

Tipos de documentación
Diátaxis Framework - Hay cuatro modos de documentación: tutoriales, guías de instrucciones, referencias técnicas y explicaciones.
Modelo de datos DITA - Hay 3 tipos de documentación, conceptos, tareas y referencia.
Tipos de documentación de JIT - Responde a 4 tipos de preguntas: ¿dónde está?, ¿cómo lo hago?, ¿qué diablos?, ¿hay otra manera?

Arquitectura de la información y navegación
Ordenación de tarjetas Ejercicio de planificación de categorías
Prueba del árbol Ejercicio de prueba de la categoría
Navegación no jerárquica Buscar, descubrir, llevar a contenidos relacionados

Gestión de proyectos
Planificación suficiente - un buen plan ahora es mejor que un plan perfecto la semana que viene
Nunca terminado - Siempre completo Ser como una rana
Ciclo del flujo de trabajo evaluar, priorizar, investigar, escribir, revisar, publicar, recibir comentarios y volver a empezar en la evaluación
Documentación justo a tiempo crear la documentación justa a tiempo
Modelos de madurez: defina las etapas de madurez del proyecto y realice un seguimiento de su progreso hacia los objetivos a lo largo del tiempo

Más recursos
Write the Docs - Learning Resources - Recursos recopilados por la comunidad de Write the Docs.
Write the Docs - Guide - Una lista de pequeñas guías sobre temas específicos relacionados con la documentación.

[jaimev]

About this thread

• This thread is meant to be a space where we can compile, organize and discuss any references we find that might help guide us on our path to improving our technical documentation.
• The first post is a wiki that anyone can edit and add new references.
• You can use this technique to link to from the first post to other themes in in the thread or just link to external documents
• This thread is meant to be a space for high level strategizing and planning of our approach to documentation.
• This thread and the post above is not a space for writing our actual documentation, that happens elsewhere
• This thread is not a space for discussing the merits of specific documentation tools. (We will open a separate thread for that.)

Acerca de este hilo

• Este hilo pretende ser un espacio en el que podamos recopilar, organizar y discutir cualquier referencia que encontremos y que pueda ayudarnos a guiarnos en nuestro camino para mejorar nuestra documentación técnica.
• El primer post es una wiki que cualquiera puede editar y añadir nuevas referencias.
• Puedes usar esta técnica para enlazar desde el primer mensaje a otros temas en el hilo o simplemente enlazar a un documento externo
• Este hilo está destinado a ser un espacio para la estrategia de alto nivel y la planificación de nuestro enfoque de la documentación.
• Este hilo y el post anterior no es un espacio para escribir nuestra documentación real, esto pasario en otro lugar
• Este hilo no es un espacio para discutir los méritos de las herramientas de documentación específicas. (Abriremos un hilo separado para eso).

[jaimev]

I’ve been searching the web for strategies and approaches to writing good documentation and have come across a lot of blog posts with useful bits of advice but nothing like a philosophical framework I was hoping for.

Then I found this site: Learning Resources — Write the Docs
which has quite a few interesting resources, especially Documentation Guide — Write the Docs with links that go into more depth about documentation principles and approaches that seem insightful. And also an actual readling list Its going to take me awhile to get through all this but these seem like people we want to talk to or follow at least.

[jamie]

These are some great resources Jaime - thanks for posting them.

Some of the highlights I found as I navigated around the guide and it’s external links:

1. It’s important to pair novices and technical people in writing docs, because novices are better at knowing what to write:

• Managing People - Documentation Guide
• Conquering Imposter Syndrome — Write the Docs

2. Over all goals to consider when writing docs: Documentation Principles — Write the Docs

3. Understanding the reader: Understand Reader - Documentation Guide

4. Structuring your documents: Documentation Structure - Documentation Guide

[jaimev]

Diataxis Framework

The Diataxis Framework is a great example of the kind of practical and theoretical approach to creating documentation that I’ve been looking for. It provides confident and opinionated guidelines for distinguishing between different types of documentation content, explains their purpose, and provides recommendations for how each should be written. Surprisingly the author recommends against using this system as part of any comprehensive strategic documentation plan but rather as a kind of thoughtful daily gardening practice in which the whole takes shape by applying the same consistent approach to each smaller part at every stage. “Be like frog.” That’s deep.

---

Diataxis Framework

El Diataxis framework es un buen ejemplo del tipo de aproximación práctica y teórica para la creación de documentación que he estado buscando. Con mucha seguridad ofrece unas pautas bastante opinionadas sobre como distinguir entre los diferentes tipos de contenido para la documentación, explica su finalidad y ofrece recomendaciones sobre cómo debe redactarse cada uno de ellos. Sorprendentemente, el autor recomienda no utilizar este sistema como parte de un plan de documentación estratégico integral, sino como una especie de práctica de jardinería meditativa cotidiana en la que el conjunto toma forma aplicando el mismo enfoque coherente a cada parte más pequeña en cada etapa. “Se como rana.” Que profundo.

[jaimev]

Start with what the reader needs

This live presentation by Beth Aitman offers up some useful rules of thumb for writing a good piece of documentation. These recommendations seem most applicable to how-to’s and tutorials. I’ve summarized what I felt were the main points here.

1. Start with what the reader needs

• help a reader to achieve a goal - what does your reader need to get out of it?
• write only the stuff down that helps them with that. don’t include stuff just because it’s connected
• ask yourself: does the reader need to know about that in this context?

2. Write less

• don’t write more documentation than you can carry - document only what you can commit to keep updated over time
• you don’t need to cover everything - focus on a few core things and cover them well
• get rid of useless or outdated documentation - bad documentation trains people to expect nothing from the docs

3. Write the outline first

• Start with an outline answering the questions:
  • Who is this for?
  • What is the reader trying to get done?
• Fill in your answers and notes as bullet points and you’re most of the way to having something useful written
• Fill in the details and make sure you’re only answering the original questions
• Headings will make your doc much more readable

4. Rubber ducking ( Explain it to yourself out loud )

• you can work out problems by speaking about them
• this is useful to kind of get you unblocked
• we find it easier to express ourselves when speaking
• a friendly kind of conversational style is much easier for readers to take in

5. Write Readably

• Use structure and formatting to avoid walls of text
  • use headings to give the reader a way to understand the information at a glance
  • use code formatting where appropriate
  • if you find yourself writing a sequence, “do this, this, and this” turn that into a list
• Keep your paragraphs nice and short
  • one idea per paragraph
  • sentences to roughly below 25 words
• Front-load sentences - if there is condition putting it first means someone can skip the other thing. “If Y is the case, do X.”
• Just instruct people directly - This can feel rude but it is kinder and useful for the reader to say this is the thing you need to do rather than it’s possible “Using Z it is possible to do X”, or using the passive voice “There is a Z that can be used to do X”. It is better to write directly: “To do X, use Z”
• Align your headings to what your user is trying to get done

6. It’s not just about documentation

• often through writing documentation, you discover much bigger problems
• think about whether you can make the underlying thing better
• if, instead of writing a doc, you can fix the thing, you should fix the thing
• Related blog post: Writing can’t fix bad design | Beth Aitman

---

Empezar con lo que tus lectores necesitan

Esta presentación en vivo de Beth Aitman ofrece algunas reglas útiles para escribir una buena documentación. Estas recomendaciones parecen más aplicables a los guías y tutoriales. He resumido lo que me parecieron ser los puntos principales aquí.

1. Empezar con lo que tus lectores necesitan

• ayudar al lector a alcanzar un objetivo - ¿qué necesita tu lector para conseguirlo?
• escribe sólo las cosas que les ayuden con eso. no incluyas cosas sólo porque están conectadas
• pregúntate a ti mismo: **¿necesita el lector saber eso en este contexto? **

2. Escribir menos

• no escribas más documentación de la que puedas cargar - documenta sólo lo que puedas comprometerte a mantener actualizado en el tiempo
• no es necesario cubrir todo - céntrate en unas pocas cosas básicas y cúbrelas bien
• Elimina la documentación inútil u obsoleta - una mala documentación hace que la gente no espere nada de los documentos

3. Escribe primero el esquema

• Empieza con un esquema que responda a las preguntas:
  • ¿A quién va dirigido?
  • ¿Qué quiere hacer el lector?
• Rellena tus respuestas y notas en forma de viñetas y ya tienes la mayor parte del camino recorrido para tener algo útil escrito
• Completa los detalles y asegúrate de responder sólo a las preguntas originales
• Las cabeceras harán que tu documento sea mucho más legible

4. “Rubber Ducking” - Explícalo a ti misma en voz alta

• puedes resolver los problemas hablando sobre ellos
• esto es útil para desbloquearse
• nos resulta más fácil expresarnos al hablar
• escribir con un estilo de conversación amigable es mucho más fácil de asimilar para los lectores

5. Escribir de forma legible

• Utiliza la estructura y el formateo para evitar los muros de texto.
  • Utilizar títulos para que el lector pueda entender la información de un vistazo.
  • Utiliza el formato de código cuando sea necesario.
  • Si te encuentras escribiendo una secuencia, “haz esto, esto y esto” conviértelo en una lista
• Mantenga sus párrafos cortos.
  • Una idea por párrafo
  • Las frases deben tener menos de 25 palabras
• Frases de carga frontal - si hay una condición ponerla primero para que alguien puede saltarse lo otro. “Si Y es el caso, haz X”.
• Instrucciones directas - Esto puede parecer grosero, pero es más amable y útil para el lector decir que esto es lo que hay que hacer en lugar de que es posible “Usando Z es posible hacer X”, o usar la voz pasiva “Hay una Z que puede usarse para hacer X”. Es mejor escribir directamente: “Para hacer X, usa Z”
• Alinee sus títulos a lo que su usuario está tratando de hacer

6. No sólo se trata de documentación

• a menudo, al escribir la documentación, se descubren problemas mucho mayores
• piensa en si puedes mejorar la cosa subyacente
• si, en lugar de escribir una documentación, puedes arreglar la cosa, deberías arreglar la cosa.
• entrada del blog relacionada: Writing can’t fix bad design | Beth Aitman

[jamie]

Wow - this is the most helpful thing I’ve read about documentation. I’m particularly grateful for the four-part division between tutorials, how-tos, explanations, and reference. Realy useful.

[jaimev]

Neil Kaplan has a lot of practical advice about getting started with the entire documentation process

A lot of this advice seems to come out of business management models but sounds reasonably useful in the context of organizing a large documentation project.

"Good enough" planning

Neil is a fan of having a rigorous but flexible strategy and plan that is just “good enough”.

• a good plan now is better than a perfect plan next week
• create a plan that’s good enough to start using now
  • who is your audience?
  • what do they need to know?
  • when do they need to know it?
  • how will you create it?
  • how much can you create?
    • be honest - don’t sign up for things that you can’t do
  • who can help you?
• record this information and share this with your
  organization - You will get feedback

Documentation Workflow Cycle

Evaluate, prioritize, research, write, review, publish, get feedback, and start again at evaluation

I like his overall documentation cycle but I have questions about doing that in coordination with others.

Content Audit

I like this practical approach to evaluating existing documentation. Definitely not something we should get stuck on though.

Research internal documentation wiki’s and support email threads for usable documentation.
List everything you found and:

• Classify as Redundant,Outdated or Trivial:
  • redundant - this information exists but there’s
    a better version somewhere else
  • outdated - things have changed significantly
  • trivial just means you’ve found a piece of content and it’s two words or it’s a sentence
• give it a level of effort - how much effort would it take to turn that into usable documentation? high,medium,low.
• Add notes
  • who you talked to
  • where you found it
• Share your results with people you’ve talked to

Gap analysis

Exercise to “ruthlessly” prioritize writing and editing.

• You’ve identified:
  • your audience
  • the audience wants and needs
  • the existing content and what state it’s in
• Plot proposed and existing documentation items in a “Value vs Level of effort” axis chart.
  • prioritize high value low effort items
  • forget about the high effort low value stuff
  • don’t spend much time on low value, low effort stuff
  • who can help out on high effort, high value items
• record this information
  • give each task/request etc. an estimated level of effort , timeframe
  • you will be wrong but you will get better

“Accept you won’t be able to do everything and that’s okay. you will still do a lot.”

---

Neil Kaplan tiene muchos consejos prácticos para empezar con todo el proceso de documentación

Algunos de estos consejos parecen salir de los modelos de gestión empresarial, pero suenan razonablemente útiles en el contexto de la organización de un proyecto grande de documentación.

Planificación "suficiente"

Neil es partidario de tener una estrategia y un plan riguroso pero flexible que sea “suficientemente bueno”.

• un buen plan ahora es mejor que un plan perfecto la próxima semana
• crea un plan que sea lo suficientemente bueno como para empezar a utilizarlo ahora
  • ¿Quién es su público?
  • ¿Qué necesitan saber?
  • ¿Cuándo necesitan saberlo?
  • ¿Cómo lo vas a crear?
  • ¿Cuánto puedes crear?
    • Sé honesto: no te apuntes a cosas que no puedes hacer.
  • ¿Quién puede ayudarte?
• Registra esta información y compártela con tu organización.
  organización - Recibirás comentarios.

Ciclo de trabajo de la documentación

Evaluar, priorizar, investigar, escribir, revisar, publicar, obtener retroalimentación y comenzar de nuevo en la evaluación

Me gusta su ciclo de documentación en general, pero tengo dudas sobre cómo hacerlo en coordinación con otros.

Auditoría de contenidos

Me gusta este enfoque práctico para evaluar la documentación existente. Sin embargo, definitivamente no es algo en lo que debamos atascarnos.

Investiga los wiki’s de documentación interna y los hilos de correo electrónico de soporte en busca de documentación utilizable.
Haz una lista de todo lo que has encontrado y:

• Clasificar como redundante, obsoleta o trivial:
  • redundante - esta información existe pero hay
    existe una versión mejor en otro lugar
  • Obsoleta: las cosas han cambiado significativamente.
  • trivial significa que has encontrado un contenido de dos palabras o una frase
• Dale un nivel de esfuerzo - ¿cuánto esfuerzo se necesitaría para convertir eso en una documentación utilizable? alto, medio, bajo.
• Añade notas
  • con quién has hablado
  • dónde lo has encontrado
• Comparte tus resultados con las personas con las que has hablado

Análisis de deficiencias

Ejercicio para priorizar “sin piedad” la escritura y la edición.

• Has identificado:
  • tu audiencia
  • los deseos y necesidades de la audiencia
  • el contenido existente y en qué estado se encuentra
• Mapa los elementos de documentación propuestos y existentes en un gráfico con el eje “Valor frente a nivel de esfuerzo”.
  • Prioriza los elementos de alto valor y bajo esfuerzo.
  • Olvídese de los elementos de alto esfuerzo y bajo valor por ahora.
  • No se debe dedicar mucho tiempo a los elementos de bajo valor y bajo esfuerzo.
  • ¿Quién puede ayudar en los elementos de alto esfuerzo y alto valor?
• Registrar esta información
  • Asigne a cada tarea/solicitud, etc., un nivel de esfuerzo y un plazo estimados.
  • Te equivocarás, pero mejorarás

“Acepta que no podrás hacerlo todo y no pasa nada, aún así harás mucho”.

[jaimev]

One of my biggest questions when I started researching this is about “information architecture” How can our documentation be organized better? This presentation by Lana Brindley offers some helpful suggestions.

Content Map

This is an exercise to help you make a critical assessment of the information architecture you already have.

Content Map you can make with a spreadsheet:

• Create column headers with for “Top Level title, Second Level title, Third level title or page name, title, url, content type”
• Fill out the details for your pages
  many pages might share the same top level title for example
• You can quickly get a sense of the distribution of content between top level second level third level by scanning your content map. In most cases you are looking for an even distribution.
• You can also get a sense of the ratio of content types

DITA Data Model

This is the model Lana uses to classify documentation types It is similar to Diataxis but limited just 3 types, Concepts, Tasks and Reference.

“Good documentation should have clearly defined sections of concepts followed by tasks followed by reference.” These types should not be mixed together. Beginners need lots of concepts and experienced users need to be able to skip the concepts and easily locate tasks and reference information.

Identifying Readers

Users use software and readers read documentation and while that venn diagram overlaps it’s not a perfect circle. Documentation readers are not just users. Staff, support team, and admins sometimes use docs even more than users. People read your docs to determine if they want to be involved in your community or if they want to use your product in their own project

Contact Readers

Try and get in contact with your readers in any way you can. Start with a series of one-on-one interviews with people you already know. Use the information you get from these interviews to create a short survey to send out to your wider audience.

Benefits of asking:

• short term
  • get direct feedback on docs
  • understand pain points
• long term
  • let people know you care about documentation
  • builds community engagement

What do readers want?

• might not be what you think they want
• not always what they say they want

User task analysis

Think of beginner, intermediate, and expert users. They will probably be interested in different parts of your system and need different types of help from your docs. The following is meant to be a quick exercise to analyze the needs of your readers.

Before you begin

• Make sure you know:
  • Top three reader types
  • cover spectrum of beginner → expert
• Top things readers want to achieve
  • doesn’t need to be exhaustive list
  • consider this for each reader type

Once you have those things you can put them in a table and work out how likely it is that a particular reader will use the documentation to do each task. Put the reader types across the top of your table and all the tasks down the side you get a matrix, you can fill out each square on the table with the likelihood that each reader type will use the docs to do each task. Note, you’re not asking if they’ll need to do a task, you’re asking if they’ll need documentation to do it

When you have all the boxes filled out you can do some simple math to score a

• 3 for high likelihood
• two for medium
• one for low

This gives each task a score, the higher the number the more critical the documentation for this task. If it’s important to everyone that means we know we need to spend more time and effort on documenting this. The highest scoring things in your table are referred to as critical paths and where you should focus first.

Organization and Navigation

Hierarchies work well when we have a bunch of things and we need to organize them but they
don’t always work very well when we need to find something.

• Think about different methods readers are using to arrive at your content.
  • Do the they arrive directly?
  • Do they search?
• Where do they arrive?
• Where do they go next?

Discovery - Lead people to information they didn’t know they needed

• Automatically generated related content
• Keyword navigation
• Use your thinking brain to come up with other methods

Design and architecture is more art than science…listen to what your readers are telling you either directly through feedback or indirectly through their actions on your site… adjust as you go… documentation architecture is constantly a work in progress.

---

Una de mis mayores preguntas cuando empecé a investigar fue sobre la “arquitectura de la información”. ¿Cómo podemos organizar mejor nuestra documentación? Esta presentación de Lana Brindley ofrece algunas sugerencias útiles.

Mapa de contenidos

Este es un ejercicio para ayudarte a hacer una evaluación crítica de la arquitectura de la información que ya tienes.

Mapa de contenidos que puedes hacer con una hoja de cálculo:

• Crear encabezados de columna con para “Título de primer nivel, título de segundo nivel, título de tercer nivel o nombre de la página, título, url, tipo de contenido”
• Rellene los detalles de sus páginas
  muchas páginas pueden compartir el mismo título de primer nivel, por ejemplo
• Puedes obtener rápidamente una idea de la distribución del contenido entre el primer nivel, el segundo nivel y el tercer nivel escaneando su mapa de contenido. En la mayoría de los casos se busca una distribución uniforme.
• También puede tener una idea de la proporción de los tipos de contenido

Identificar lectores

Las personas usuarios utilizan software y las personas lectores leen la documentación y aunque ese diagrama de venn se superpone no es un círculo perfecto. Les lectores de la documentación no son sólo les usuarios. El personal, el equipo de soporte y les administradores a veces utilizan la documentación incluso más que les usuarios. La gente lee tu documentación para determinar si quieren participar en tu comunidad o si quieren usar tu producto en su propio proyecto

Contacto con lectores

Intenta ponerte en contacto con tus lectores de cualquier manera que puedas. Comienza con una serie de entrevistas individuales con personas que ya conoces. Utiliza la información que obtengas de estas entrevistas para crear una breve encuesta que enviarás a tu público más amplio.

Ventajas de preguntar:

• Corto plazo
  • Obtener información directa sobre los documentos.
  • Comprender los puntos débiles.
• A largo plazo
  • Permite a la gente saber que se preocupa por la documentación.
  • crea un compromiso con la comunidad

¿Qué quieren sus lectores?

• Puede que no sea lo que tu crees que quieren
• no siempre es lo que dicen que quieren

Análisis de las tareas del usuario

Piensa en usuarios principiantes, intermedios y expertos. Probablemente estarán interesados en diferentes partes de su sistema y necesitarán diferentes tipos de ayuda de sus documentos. Lo siguiente pretende ser un ejercicio rápido para analizar las necesidades de tus lectores.

Antes de empezar

• Asegúrese de conocer:
  • Los tres principales tipos de lectores
  • Cubrir el espectro de principiante → experto
• Las principales cosas que los lectores quieren conseguir
  • no tiene por qué ser una lista exhaustiva
  • Considere esto para cada tipo de lector

Una vez que tengas esas cosas, puedes ponerlas en una tabla y calcular la probabilidad de que una persona lector concreto utilice la documentación para realizar cada tarea. Si colocas los tipos de lectores en la parte superior de la tabla y todas las tareas en los laterales, obtendrás una matriz en la que podrás rellenar cada casilla de la tabla con la probabilidad de que cada tipo de lector utilice la documentación para realizar cada tarea. Ten en cuenta que no estás preguntando si necesitarán hacer una tarea, sino si necesitarán la documentación para hacerla.

Cuando hayas rellenado todas las casillas, puedes hacer algunos cálculos sencillos para obtener una puntuación de

• 3 para una alta probabilidad
• 2 para la probabilidad media
• 1 para baja

Esto da una puntuación a cada tarea, cuanto más alto sea el número, más crítica será la documentación para esta tarea. Si resulta importante para todes, significa que debemos dedicar más tiempo y esfuerzo a documentarla. Las cosas con mayor puntuación en tu tabla se denominan rutas críticas y es donde debes centrarte primero.

Organización y navegación

Las jerarquías funcionan bien cuando tenemos un montón de cosas y necesitamos organizarlas pero no siempre funcionan muy bien cuando necesitamos encontrar algo.

• Piensa en los diferentes métodos que utilizan los lectores para llegar a tu contenido.
  • ¿Llegan directamente?
  • ¿Buscan?
• ¿Dónde llegan?
• ¿A dónde van después?

Descubrimiento - Llevar a la gente a información que no sabían que necesitaban

• Contenido relacionado generado automáticamente
• Navegación por palabras clave
• Utilice su cerebro pensante para idear otros métodos

El diseño y la arquitectura son más arte que ciencia…escucha lo que te dicen tus lectores, ya sea directamente a través de los comentarios o indirectamente a través de sus acciones en tu sitio… ajústalo sobre la marcha… la arquitectura de la documentación es un trabajo en proceso continuo.

[jaimev]

Continuing on the topic of information architecture…

When trying to decide how to organize topics/tasks into categories there are two practical exercises I found repeated in several presentations and tutorials. Card sorting and Tree Tests . Both of them are simple enough that I think I can describe them here. Feel free to search for these terms to see tons of tutorials and variations.

Card Sorting

Write all the the tasks, questions, and pieces of information your readers are looking for onto small cards. Invite your readers to help group these cards together based on affinity. The exercise can be done in person or virtually.

The exercise can run as Open card sorting in which participants are asked to first create their own groupings of related cards and afterwards create their own category or header names for those groupings. This can give you insight about readers mental model for grouping. Closed card sorting can be used to test already existing categories. Hybrid ersions of the exercise that allow for some fixed categories can also be run.

You can also constrain participants to create categories for a category type like “thematic subjects”, “user experience level”, “associated tools” or allow for hybrid categorization.

The important thing is to run the same exercises with a variety of potential documentation readers. These can be done both collectively or individually by all participants to avoid bias.

The results should be captured and tabulated. That data can be used to graph results in different ways. A couple of examples are:

Similarity Matrix - The results of card sorting are graphed to illustrate how often participants paired two cards together in the same groups. This might show you what content most users feel is strongly related.

Dendrogram - An automatic hierarchical statistical clustering of results that might give you some insight about how popular different groupings are at different levels of hierarchy.

Tree Testing

This is another exercise cited frequently and is used to test how easy it is for readers to find information with your chosen set of categories. Participants are given the name of a specific task or piece of information and asked to find that information in a pre-prepared hierarchical menu of categories. This might help you identify problem areas or compare results between two different category structure proposals.

There is a surprising amount of information about these techniques on the internet and and niche online platforms have been created to to help UX designers and information architects run these tests and analyze results. Unfortunately I wasn’t immediately able to find any open source alternatives to these platforms.

---

Siguiendo con el tema de la arquitectura de la información…

Al tratar de decidir cómo organizar los temas/tareas en categorías hay dos ejercicios prácticos que encontré repetidos en varias presentaciones y tutoriales. La clasificación de tarjetas y las pruebas de árbol . Ambos son lo suficientemente sencillos como para poder describirlos aquí. Siéntase libre de buscar estos términos para ver toneladas de tutoriales y variaciones.

Ordenación de tarjetas

Escriba todas las tareas, preguntas y piezas de información que sus lectores están buscando en pequeñas tarjetas. Invita a tus lectores a que te ayuden a agrupar estas tarjetas por afinidad. El ejercicio puede hacerse en persona o virtualmente.

El ejercicio puede llevarse a cabo como una clasificación de tarjetas abierta en la que se pide a las personas que participan que primero creen sus propias agrupaciones de tarjetas relacionadas y que después creen sus propias categorías o nombres de cabecera para esas agrupaciones. Esto puede dar una idea del modelo mental de los lectores para la agrupación. La clasificación de tarjetas cerradas puede utilizarse para comprobar las categorías ya existentes. También se pueden realizar versiones híbridas del ejercicio que permitan algunas categorías fijas.

Lo importante es realizar los mismos ejercicios con una variedad de lectores potenciales de la documentación. Pueden hacerse de forma colectiva o individual por todos los participantes para evitar sesgos.

Los resultados deben capturarse y tabularse. Esos datos pueden utilizarse para graficar los resultados de diferentes maneras. Un par de ejemplos son:

Matriz de similitud - Los resultados de la clasificación de tarjetas se grafican para ilustrar la frecuencia con la que sus participantes colocaron dos tarjetas en los mismos grupos. Esto puede mostrar los contenidos que la mayoría de sus lectores consideran fuertemente relacionados.

Diagrama - Una agrupación estadística jerárquica automática de los resultados que puede dar una idea de la popularidad de las diferentes agrupaciones en diferentes niveles de jerarquía.

Prueba del árbol

Este es otro ejercicio que se cita con frecuencia y que se utiliza para comprobar qué tan fácil es para tus lectores encontrar la información con el conjunto de categorías elegido. Se da a a las personas participantes el nombre de una tarea o información específica y se les pide que encuentren esa información en un menú jerárquico de categorías preparado de antemano. Esto puede ayudarle a identificar áreas problemáticas o a comparar los resultados entre dos propuestas diferentes de estructura de categorías.

Hay una cantidad sorprendente de información sobre estas técnicas en Internet y se han creado plataformas online para ayudar a personas que son diseñadores de UX u arquitectos de la información a realizar estas pruebas y analizar los resultados. Lamentablemente, no he podido encontrar de inmediato ninguna alternativa de código abierto a estas plataformas.

[jaimev]

In this presentation Bri Hillmer offers a slightly different take on organizing a documentation project. She promotes a “just in time” documentation philosophy meant to compliment Agile software development “practices and values”. Regardless of how you might feel about Agile some of these recommendations seem useful for an org working with our particular constraints.

Just-in-time

We create just enough documentation just in time

Why are we inclined to write feature guides or “Just in case” documents for theoretical users?

• Easy place to start
• Helps existing and prospective users learn about features

What’s wrong with feature guides?

• Doesn’t help users solve problems
• Requires familiarity with terminology
• Difficult to search
• Difficult to use
• Difficult to produce

“we’re terrible at anticipating what questions our users have so why not just wait until they ask and then write the document.”

If your first idea is: “I could code all the tickets and score them based on complexity and use that data to make decision about what articles need to be written.” Chill out, If you just write small articles in response to every reasonable question that’s coming into the support queue that’s a good place to start.

You don’t have time to collect data and write documentation so just start turning out content. A lot of the articles can start out as the minimum viable documentation and can be as little as one or two paragraphs.

Lessons:

• It’s OK to have a LOT of content- average user wants to search your knowledgebase, not browse
• Docs can be updated just in time too! update outdated documents that users bring to your attention
• Document workarounds
• Documentation is its own ‘service’, to the world.

How to JIT document

• create a systematic process
• document it fast
• be a JIT champion! send out monthly updates
• Let go! - “I wanted our entire knowledge base to be polished and every article to be useful to everybody and I had to let go of that- but it’s working”

What is worth documenting?

What is worth documenting?
Focus on the intersection between what users want to accomplish, what the system can do, and what users can’t figure out. However, its ok to document adjacent things users want even if its outside of the system you’re supporting.

Just in Time workflow

1. Ticket comes in
2. Support team member responds- The support team member can decide if their response or the thread is generalizable. If the answer is yes tag or e-mail the documentation team to work on it.
3. If the document is created send it back to support team member for feedback and if created in a timely fashion back to the user who opened the ticket to signal that you are listening.

After Writing

1. Monitor traffic - before and after

• Relevant data tracking
  • Unique sessions per day
  • Pageviews per session
  • Time spent on page - 2 minutes or more on an article is a quality view, they are reading the content and getting their answer
• unpublish low traffic docs
• improve high traffic docs

2. let people know what you’re doing
3. get and respond to feedback quickly

JIT Docs Types

She also offers her own documentation types. As someone who has spent a lot of time providing technical support I find these very entertaining.

• Buried in the user interface that people can’t find
• How Do I - walkthroughs, many features and steps to achieve complete task
• FAQ - What the hell documents? “Why did this happen? This seems like it shouldn’t happen- but there are ways that it can happen.”
• Workarounds - features that are not in the app but someone has come up with a way to make it happen.

---

En esta presentación Bri Hillmer ofrece una visión un poco diferente sobre como organizar un proyecto de documentación. Promueve una filosofía “justo a tiempo” de la documentación destinada a complementar las “prácticas y valores” del desarrollo de software ágil. Independientemente de lo que se piense sobre Agile, algunas de estas recomendaciones parecen útiles para una organización que trabaja con nuestras restricciones.

Justo a tiempo

Creamos la documentación justa a tiempo

Por qué nos inclinamos a escribir guías de funcionamiento o documentos “Just in case” para los usuarios teóricos?

• Es un lugar fácil para empezar
• Ayuda a los usuarios actuales y potenciales a conocer las características

¿Qué tienen de malo las guías de funcionamiento?

• No ayudan a los usuarios a resolver problemas.
• Requiere estar familiarizado con la terminología
• Difícil de buscar
• Difícil de usar
• Difícil de producir

“Somos terribles a la hora de anticiparnos a las preguntas de nuestros usuarios, así que por qué no esperar a que pregunten y entonces escribir el documento”.

Si tu primera idea es: “Podría codificar todos las peticiones de soporte y calificarlas en función de su complejidad y utilizar esos datos para tomar decisiones sobre los artículos que hay que escribir”. Tranquilízate, si sólo escribes pequeños artículos en respuesta a cada pregunta razonable que llega a la cola de soporte es un buen punto de partida.

No tienes tiempo para recopilar datos y escribir documentación, así que mejor empieza a producir contenido. Muchos de los artículos pueden empezar como la documentación mínima viable y pueden ser tan sólo uno o dos párrafos.

Lecciones:

• Está bien tener un montón de contenido - el usuario medio quiere buscar en su base de conocimientos, no navegar
• Actualice los documentos obsoletos que los usuarios te señalen.
• Documenta las soluciones “provisionales”
• La documentación es su propio “servicio”, al mundo.

Cómo documentar JIT

• crear un proceso sistemático
• documente rápidamente
• ¡Sea un campeóna del JIT! envíe actualizaciones mensuales
• ¡Soltar! - “Quería que toda nuestra base de conocimientos estuviera pulida y que cada artículo fuera útil para todo el mundo, y he tenido que soltarlo, pero está funcionando”

¿Qué vale la pena documentar?

Céntrate en la intersección entre lo que los usuarios quieren conseguir, lo que el sistema puede hacer y lo que los usuarios no pueden resolver. Se genoroso, está bien documentar las cosas adyacentes que los usuarios quieren, incluso si están fuera del sistema que estás apoyando.

Flujo de trabajo Just in Time

1. El ticket llega
2. El equipo de soporte puede decidir si su respuesta o el hilo son generalizables. Si la respuesta es afirmativa, etiqueta o envía un correo electrónico al equipo de documentación para que trabaje en él.
3. Si se crea el documento, envíelo al miembre del equipo de soporte para que le dé su opinión y, si se crea a tiempo, devuélvalo al persona que abrió el ticket para indicarle que le está escuchando.

Después de escribir

1. Monitorear el tráfico - antes y después

• Seguimiento de datos relevantes
  • Sesiones únicas por día
  • Páginas vistas por sesión
  • Tiempo de permanencia en la página - 2 minutos o más en un artículo es una vista de calidad, están leyendo el contenido y obteniendo su respuesta
• Retirar la publicación de documentos de bajo tráfico
• Mejorar los documentos de alto tráfico

2. comunique a la gente sobre el trabajo que está realizando
3. obtener y responder a la retroalimentación rápidamente

Tipos de documentación JIT

También ofrece sus propios tipos de documentación. Como alguien que ha pasado mucho tiempo prestando soporte técnico me parecen muy entretenidos.

• Tan enterrado en la interfaz de usuario que la gente no lo encuentra
• ¿Cómo lo hago? guías con muchas características y pasos para lograr una tarea completa
• FAQ - Documentos ¿Qué demonios? “¿Por qué ha ocurrido esto? Esto parece que no debería suceder- pero hay maneras de que pueda suceder”.
• Soluciones alternativas o provisionales - características que no están en la aplicación, pero alguien ha ideado una manera de hacer que suceda.

[jaimev]

Fast thinking and slow thinking

In this this presentation Anita Diamond introduces the concept of fast thinking and slow thinking based on the theories of psychologist Daniel Kahneman.

Fast thinking:: providing familiar language and structure makes it easier on readers to scan through documentation quickly without feeling overwhelmed. Surrounding new vocabulary and concepts with familiar language can help readers derive the meaning from the context.

Caveat: This kind of “fast thinking” and reading mode is also prone to errors when introducing new concepts.

Slow thinking:: If the stakes are high, and there is a key piece of information you want readers to stop and concentrate on, you will need to trigger a transition to a more slow contemplative thinking mode. In a web page you can use all of the resources the medium allows, language, formatting or interface elements that might prompt the reader to stop, memorize, calculate or interpret what is in front of them.

Caveat: This mode of thinking requires much more effort from the reader and forcing them to spend too much time there can be exhausting.

---

El pensamiento rápido y el pensamiento lento

En esta presentación Anita Diamond introduce el concepto de el pensamiento rápido y el pensamiento lento, basado en las teorías del psicólogo Daniel Kahneman.

Pensamiento rápido: proporcionar un lenguaje y una estructura familiares facilita a los lectores la lectura rápida de la documentación sin sentirse abrumados. Rodear un nuevo vocabulario y conceptos con un lenguaje familiar puede ayudar a los lectores a deducir el significado a partir del contexto.

Caveat: Este tipo de “pensamiento rápido” y modo de lectura también es propenso a errores cuando se trata de introducir nuevos conceptos.

Pensamiento lento: Si se trata de algo importante y hay una información clave en la que quieres que los lectores se detengan y se concentren, tendrás que provocar una transición a un modo de pensamiento contemplativo más lento. En una página web se pueden utilizar todos los recursos que permite el medio, el lenguaje, el formato o los elementos de la interfaz que pueden obligar al lector a detenerse, memorizar, calcular o interpretar lo que tiene enfrente.

Caveat: Este modo de pensamiento requiere mucho más esfuerzo por parte del lector y obligarle a pasar demasiado tiempo en él puede resultar agotador.

[mercovich]

Hola a todes.

Hay una actividad que podría darnos muchísima información acerca del modelo conceptual de nuestros usuaries, con la cual podemos ayudar a definir la arquitectura de la información acá (orgánica, flexible, evolutiva, adaptativa, etc, pero basada en info certera). Junto con esa información también recabamos valores, prioridades, léxico específico, y las relaciones entre esos conceptos.

Se hace con 12 a 14 personas al mismo tiempo en casi 3 horas y luego un par de análisis para formalizar el resultado en un informe. Si hay un mínimo manejo de algunas herramientas tipo mural, se puede hacer en línea.

Es una secuencia de

1. lluvia de ideas (individual primero y luego socializada), luego
2. ordenamiento de tarjetas (las generadas en la primera etapa), y finalmente…
3. Priorización.

Se llama taller de mapeo o KJ (por el japonés que la inició). Si les parece útil será un placer contarles más quizás organizarla y/o facilitarla.

Abrazos…

PD: tipeo desde móvil, perdón la brevedad.