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

Technology Infrastructure and Services
7

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
2 Likes