What style of documentation should product managers use in order to communicate the appropriate message?

La documentación es uno de los componentes más cruciales y poco valorados de cualquier proyecto de código abierto, y no debe tomarse a la ligera.

En general, la mayoría de los proyectos de código abierto no reciben la atención adecuada simplemente porque sus autores no están realmente interesados, no son capaces o no tienen tiempo para crear un entorno de documentación efectivo para su API y producto.

Aunque tu aplicación sea excelente, si la documentación es inadecuada, los usuarios no podrán beneficiarse de su uso.

Incluso si no tienen más remedio que utilizarla por cualquier motivo, no podrán hacerlo de manera efectiva o de la forma en que te gustaría que lo hicieran.

Aprender a producir buena documentación requiere un esfuerzo significativo, así como revisar periódicamente otros proyectos de documentación. Créeme —como alguien que ha creado abundante documentación para Docsie– si estás desarrollando código que será utilizado por alguien más que tú, y especialmente si esas personas son tus clientes, tu producto debe estar bien documentado, formateado y presentado dinámicamente.

¿Cuál es la diferencia entre tutoriales, guías prácticas, explicaciones y referencias?¶

Muchas personas creen erróneamente que estos cuatro términos se refieren a lo mismo. Sin embargo, expresan significados diversos. Estos diferentes tipos de documentación son esenciales y tienen diferencias clave:

Documentación de tutoriales: Este tipo de documentación está orientada a la formación y basada en información.

Guías prácticas/Manuales de usuario: Estas documentaciones explican cómo resolver problemas específicos mediante una serie de pasos para lograr un objetivo concreto.

Documentación explicativa: Son documentos tipo artículo diseñados para ayudar al usuario a obtener una comprensión más profunda de un producto mediante explicaciones y contexto.

Documentación de referencia: Está diseñada para informar al usuario sobre nuevas funcionalidades y sus usos. Puede ser muy "técnica" en forma de documentación para desarrolladores, pero también puede traducirse en notas de versión más amigables para el usuario final.

Razones para producir documentación de alta calidad¶

Antes de continuar, es crucial comprender por qué la documentación competente es una necesidad importante pero poco valorada en la sociedad actual. La disponibilidad de documentación extensa y bien escrita es uno de los criterios más importantes para lograr una amplia adopción, especialmente en proyectos de código abierto donde prácticamente cada acción está disponible para el público y donde dichas actividades juegan un papel crucial en el éxito del proyecto.

Veamos las razones más importantes para escribir documentación efectiva.

Permite crear una mejor experiencia de incorporación para tus clientes¶

Cuando proporcionas documentación adecuada de tu producto a tus clientes, les ayudas a sentirse más cómodos con tu producto y protegidos por sus directrices específicas. Para que esto ocurra, debes:

1. Asegurar que la documentación del producto sea visible y fácilmente accesible, ya sea a través de enlaces dentro de la aplicación o bajo una plataforma de documentación con búsqueda.

2. Garantizar que esté bien escrita y ayude al cliente a encontrar su respuesta rápida y fácilmente.

Un consejo: escribe tu documentación una sola vez, y será consultada una y otra vez cuando nuevos clientes se incorporen a tu empresa.

Como consecuencia, hay menos consultas de soporte¶

Los clientes que leen y entienden tu documentación tienen más probabilidades de comprar tu producto. Cuando los clientes no pueden resolver algo, puede ser muy frustrante y pueden comenzar a culpar a tu producto.

Algunos clientes pueden contactar inmediatamente al equipo de soporte si encuentran un problema; pero si la documentación es atractiva, accesible y comprensible, podrán resolver sus propios problemas sin necesidad de consultarte, lo que a su vez les hará sentirse más capacitados.

Ayuda a apoyar a tu propio equipo¶

Una base de conocimientos sólida también puede utilizarse para ayudar a los miembros de tu equipo. Tu equipo interno debe estar informado sobre nuevas funciones, hojas de ruta planificadas, documentación de API y todo lo necesario para mantener a todos en la misma página.

Instrucciones paso a paso para escribir documentación efectiva¶

Escribir el contenido del documento y organizar esta actividad son tareas completamente distintas de determinar qué tono usar y cómo asegurar que tu documentación sea comprensible. Según O'Reilly, existen 8 reglas para una buena documentación:

1. Crear documentación que invite al lector.

2. Producir documentación completa que cubra todas las áreas del proyecto.

3. Producir material fácil de escanear y entender.

4. Crear documentación que demuestre cómo utilizar el producto mediante casos prácticos.

5. Escribir documentación que contenga repetición donde sea necesario.

6. Escribir documentación que esté actualizada.

7. Escribir documentación a la que sea fácil contribuir.

8. Escribir documentación que sea fácil de encontrar y entender.

Estos elementos se centran principalmente en el contenido. A continuación, veremos el "cómo" estructurar esta información en seis pasos:

Decide qué debes documentar¶

Tómate tiempo para considerar qué tipo de documentación vas a producir: ¿es un tutorial, un documento de referencia, un manual de instrucciones o una explicación?

Ten en cuenta que la naturaleza de tu producto tendrá un impacto directo en el tipo de documentación que serás responsable de crear.

Crea un marco¶

Construye primero una base para tu documentación. Puede ser algo muy pequeño al principio, con solo unos pocos grupos, pero con el tiempo, toda la plataforma que estás construyendo comenzará a crecer en tamaño y complejidad. Debes revisar tu estructura organizativa regularmente.

Recuerda que eres el instructor y eres responsable de cómo aprenden tus alumnos. Ellos seguirán tus indicaciones; por lo tanto, cuanto más tiempo dediques a la estructura, más éxito tendrán tus alumnos.

Aprovecha siempre las técnicas multimedia¶

Asegúrate de utilizar videos, dibujos y estilos variados e integrarlos directamente en tu documentación. Docsie permite incorporar cualquiera de estos elementos en nuestra plataforma para facilitar este proceso.

No solo ayudarán a los consumidores a entender mejor la información que expresas, sino que también proporcionarán una excelente optimización para motores de búsqueda, lo que generará un mayor número de leads de alta calidad gracias a tu documentación dinámica.

Asegúrate de que sea localizable¶

Existen diferencias en las capacidades de búsqueda de diferentes plataformas de base de conocimientos: algunas solo ofrecen búsquedas básicas sin posibilidad de profundizar en segmentaciones (lo cual está bien si no tienes miles de archivos), mientras que otras ofrecen opciones de consulta que te permiten buscar no solo en documentos sino también en nombres de usuario.

Sin embargo, hay algo crítico: debes utilizar una herramienta que permita búsquedas rápidas. Una función de búsqueda integrada en la aplicación facilita la búsqueda de archivos y obtener una vista previa sin salir de la aplicación.

Docsie te permite tener una navegación dinámicamente localizable para acceder fácilmente a la información.

Esfuérzate constantemente por mejorar y actualizar¶

Crear y usar documentos es difícil porque las personas que los generaron o se beneficiaron de ellos los olvidan rápidamente. Los documentos también enfrentan varios desafíos durante su recorrido.

Con el tiempo, la estructura de carpetas adquiere la apariencia de un cementerio, ya que la documentación más antigua tiende a permanecer en una posición inferior en la pantalla.

Asegúrate de revisar tu documentación antigua y hacer mejoras, y anima a tus colegas a hacer lo mismo de vez en cuando. Docsie te permite crear actualizaciones a través de nuestro avanzado sistema de versiones que es simple y fácil de usar.

Reflexiones finales:¶

¿Quieres saber más sobre cómo escribir documentación efectiva? Para profesionales de documentación de software, hay una gran cantidad de blogs e información disponible aquí.