6 consejos para mejorar tu documentación

Imagina que tu equipo tuviese que pasar por todos los problemas que tuviste que pasar tu, para resolver cada error que se presenta. Que tuviese que adivinar cual es el procedimiento a seguir para hacer lo que sea. Que tus clientes tuviesen que adivinar que hacer o cómo hacer lo que has creado para ellos.

Para todos esos casos y más, existe la documentación. Textos estructurados y pensados para explicar como funciona lo que has creado.

Es parte fundamental de cualquier producto o empresa. Sin embargo, usualmente dejado de lado. Si eres un creador de productos digitales de cualquier tipo, plantillas de Notion, cursos, etc. Tienes que hacer documentación.

Lo entiendo, hacer una documentación es tedioso y fastidioso, no es divertido. Pero pese a su naturaleza aburrida, hay que hacerlas. Facilitan la vida de los usuarios y los creadores por igual, al resolver o aclarar por adelantado problemas o funcionamiento.

Dani y Alejandra hacen un trabajo increíble con las documentaciones de las plantillas de Notionología.

Aquí unos consejos para hacer subir el nivel de tu documentación

1. Empieza preguntándote sobre el lector

La documentación no se escribe por diversión, status o compromiso. La escribes para facilitar a los usuarios el uso de lo que has creado. Es básicamente un manual de instrucciones.

La documentación ES PARA LOS USUARIOS.

La forma más sencilla de empezar es preguntarte:

  • ¿Qué necesita mi usuario?
  • ¿Qué quiere lograr?
  • ¿En dónde se puede confundir o equivocar?
  • ¿El usuarios realmente necesita saber esto?
  • ¿Cómo puedo facilitar la tarea del usuario?

2. Escribe menos

Nadie revisa una documentación por diversión. Los usuarios quieren encontrar algo específico rápidamente. Escribe lo menos que puedas para dejar clara la solución, funcionamiento o problema. No te extiendas más de lo absolutamente necesario.

Curiosamente, escribir menos es precisamente lo que quieres hacer con una tarea tan aburrida como escribir una documentación. Estos consejos son buenos para el usuario y para el creador por igual.

3. Ideas generales primero

Al responder las preguntas del primer punto, dentro de cada paso de tu producto o empresa, naturalmente verás que hay temas, partes de tu mismo producto que se diferencian claramente, escríbelos. Son la columna vertebral de tu documentación.

Al descubrir un tema, hazte las mismas preguntas del primer consejo. Encontrarás sub-temas hasta los niveles que sean necesarios para quedar con las respuestas más cortas y concisas posible.

Es más fácil desarrollar una documentación yendo de lo más general a lo más particular.

Los tópicos ayudan con la navegación de la documentación. Un solo texto inmenso es difícil de navegar, es difícil conseguir respuestas allí. Si lo separas en tópicos, las personas pueden ver títulos y subtítulos que los vayan apuntando hacia su interés o necesidad específica.

4. Mantenlo casual

Si no sabes como explicar algo, intenta explicárselo a alguien hablado como ejercicio para desbloquear las ideas. Si puedes escribir la documentación con ese mismo lenguaje, de la misma manera como se lo dirías a alguien en persona, hazlo.

Sé que la opción no siempre es posible, pero el tono conversacional facilita que las personas entiendan lo que sea. Pone menos presión y facilita la escritura de todo el texto.

5. La legibilidad es importante

Ya tocamos un poco este punto en el consejo Nº 3. Es importante que la documentación no sea un bloque de texto inmenso y aburrido en ningún momento.

Aburres al usuario, lo confundes y lo desmotivas a consumir la importante información de tu documentación.

  • Si tienes varios puntos dentro de un párrafo, divídelos en listas. Si la jerarquía es importante dentro de esos puntos, usa una lista de números o letras.
  • Si hay una información particularmente importante a la que deban prestar atención, usa bloques de citas (blockquote) o resalta un estilo diferente, como un callout de Notion.
  • La división en títulos es importante también. Trata de que las ideas sean lo más pequeñas y concisas posible. Escribe lo menos posible, sé directo, claro y conciso.
  • Evita los adjetivos y conectivos. Usa punto y seguido para reemplazarlos. En ves de decir: "Es extremadamente importante que hagas esto de la siguiente manera:". Mejor: "Es importante hacerlo así:". Incluso mejor: "La forma correcta:"

Siempre que puedas eliminar una palabra, hazlo sin piedad.

6. Las documentación no es una varita mágica

Si algo no funciona, explicarlo perfectamente no va a hacer que lo haga. Es importante saber diferenciar entre errores que puede cometer y resolver el usuario y problemas fundamentales dentro del producto o empresa.

El objetivo es escribir lo menos posible, tener que explicar lo menos posible. Cuantos menos errores y situaciones haya, menos tienes que escribir.

En otras palabras, la mejor documentación es un producto o empresa que funciona perfectamente. Utópico, lo sé, pero siempre perseguible.

Conclusión

Estos han sido los 6 consejos para mejorar tu documentación. También son buenos consejos para escribir artículos en línea.

Sé que explicar las cosas que sabemos puede ser fastidioso, especialmente si tenemos la idea de que: "Un producto debe ser usable sin explicación". Pero en muchos casos, eso es imposible.

Una documentación bien escrita va a ahorrar tiempo y frustraciones a tus usuarios, dejando espacio para que te adoren aún más. También ahorrará tiempo y recursos de atención al cliente personalizada.

Por donde lo veas, es un ganar-ganar.

Si ya has escrito documentaciones antes, me encantaría saber ¿Cómo las haces? ¿Qué consejo agregarías a la lista?

Artículos relacionados

No abandones el barco y sigue leyendo otros artículos que te pueden resultar de interés.