¿Qué estilo de documentación deben utilizar los jefes de producto para transmitir el mensaje adecuado?

*La documentación es uno de los componentes más cruciales e infravalorados 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, son incapaces o no tienen tiempo para crear un entorno de documentación eficaz para la documentación de sus API y productos.

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

Sin embargo, aunque no tengan más remedio que utilizarla por el motivo que sea, no podrán hacerlo con éxito ni de la manera que a usted le gustaría.

Comprender cómo producir una documentación excelente requiere mucho trabajo, al igual que revisar periódicamente otros proyectos de documentación. Pero créeme, como alguien que ha creado una plétora de documentación para Docsie, si estás creando código que va a ser utilizado por alguien que no eres tú, y particularmente si esas personas son tus clientes, tu producto debe estar bien documentado, formateado y presentado dinámicamente.

Cuando se trata de tutoriales, instrucciones, explicaciones y referencias, ¿cuál es la diferencia?

Muchas personas creen erróneamente que las cuatro frases se refieren a lo mismo. Sin embargo, expresan significados muy diversos. Estos distintos tipos de documentación son bastante esenciales y presentan algunas diferencias clave:

Documentación tutorial: Estos tipos de documentación son documentación basada en información y orientada a la formación.

Documentación de Guías de Usuario: Las documentaciones de guías de usuario expresan cómo resolver problemas específicos a través de una serie de pasos para lograr un objetivo específico.

Documentación explicativa: Son documentaciones tipo artículo que están diseñadas para ayudar al usuario/lector a obtener una comprensión más profunda de un producto a través de varias explicaciones y contexto de fondo.

Documentación de Notas de Referencia: Esta documentación está diseñada para informar al usuario de la descripción de varias actualizaciones de nuevas características y usos. Este tipo de documentación puede ser muy "cruda" en forma de documentación para desarrolladores, pero también puede traducirse en notas de publicación más fáciles de entender para el usuario final.

Razones para producir documentación de alta calidad

Antes de continuar, es fundamental comprender por qué la redacción de documentación competente es una necesidad muy importante, aunque poco valorada, en la sociedad actual. La disponibilidad de una documentación extensa y bien redactada es uno de los criterios más importantes para lograr una adopción generalizada, sobre todo en proyectos de código abierto en los que prácticamente todas las acciones están a disposición del público y en los que dichas actividades desempeñan un papel crucial para el éxito del proyecto.

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

Le permite crear una mejor experiencia de incorporación para sus clientes.

Si proporciona a sus clientes la documentación adecuada sobre su producto, les ayudará a sentirse más cómodos con él y protegidos por sus directrices específicas. Para que esto ocurra, debe hacer lo siguiente:

1. Asegúrese de que la documentación de su producto es visible y fácilmente accesible, ya sea a través de enlaces dentro de la aplicación o en una plataforma de documentación en la que se puedan realizar búsquedas.

2. Asegúrese de que estén bien redactados y ayuden al cliente a encontrar su respuesta de forma rápida y sencilla.

Un consejo es que escriba su documentación una sola vez, ya que será digerida una y otra vez cuando su empresa incorpore nuevos clientes.

Como consecuencia, habrá menos consultas de soporte.

Los clientes que leen y comprenden su documentación tienen más probabilidades de adquirir sus productos. Cuando los clientes son incapaces de averiguar algo, puede ser bastante agravante, y pueden empezar a culpar a su producto en su lugar.

Algunos clientes pueden ponerse en contacto instantáneamente con el personal de asistencia o enviarle un correo electrónico si se encuentran con un inconveniente; pero, si la documentación es atractiva, fácilmente accesible e inteligible, podrán resolver sus propios problemas sin necesidad de consultarle a usted, lo que, a su vez, les hará sentirse más capacitados.

Te ayuda a apoyar a tu propio equipo.

Una base de conocimientos sólida también puede utilizarse para ayudar a los miembros de tu propio equipo. Así, su equipo interno debe estar informado sobre las nuevas características, las hojas de ruta previstas, la documentación de la API y todo lo necesario para mantener a todos en la misma página.

Instrucciones paso a paso sobre cómo escribir una documentación eficaz

Escribir la sustancia del documento y organizar esta actividad son dos tareas completamente distintas de determinar qué tono utilizar y cómo asegurarse de que su documentación es comprensible. Como afirma O'Reilly, existen 8 reglas para una documentación excelente:

1. Crea documentación que resulte atractiva para el lector.

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

3. **3. Producir material fácil de entender.

4. 4. Crear documentación que demuestre cómo utilizar el producto a través de casos prácticos.

5. 5. Escribir documentación que contenga repeticiones cuando sea necesario.

6. **6. Redactar documentación actualizada.

7. 1. Escribir documentación a la que sea fácil contribuir.
8. 1. Escribir documentación que sea fácil de descubrir y comprender.

Estos elementos se refieren sobre todo al contenido. A continuación, entraremos en el "cómo" estructurar esta información en seis pasos:

Tome una decisión sobre lo que debe registrar.

Tómese un tiempo para pensar qué tipo de documentación va a producir antes de empezar: ¿es un tutorial, un documento de referencia, un manual de instrucciones o una explicación?

Ten en cuenta que la naturaleza de tu producto influirá directamente en el tipo de documentación que tendrás que crear.

Cree un marco.

Construya primero una base para su documentación. Esto puede ser algo muy minúsculo al principio, y puede comprender sólo unos pocos grupos, pero con el tiempo, toda la plataforma sobre la que estás construyendo empezará a crecer en tamaño y complejidad. Debes revisar periódicamente tu estructura organizativa.

Tenga en cuenta que usted es el profesor y, en última instancia, el responsable de cómo aprenden sus alumnos en clase. Se guiarán por sus instrucciones; por tanto, cuanto más tiempo dedique a la estructura, más éxito tendrán sus alumnos en sus esfuerzos.

Aproveche siempre las técnicas multimedia adecuadas.

Asegúrate de hacer uso de vídeos, dibujos y estilos variados y conéctalos directamente a tu documentación. Docsie permite incrustar cualquiera de ellos dentro de nuestra plataforma para facilitar este proceso.

No sólo ayudarán a los consumidores a comprender mejor la información que expreses, sino que también proporcionarán una fantástica optimización para los motores de búsqueda, lo que conducirá a un mayor número de clientes potenciales de alta calidad como resultado de tu documentación dinámica.

Asegúrese de que se pueden realizar búsquedas.

Existen diferencias en las capacidades de búsqueda de las distintas plataformas de bases de conocimiento: algunas sólo ofrecen una búsqueda básica sin posibilidad de profundizar en las segmentaciones (lo que técnicamente está bien si no tienes miles de archivos), mientras que otras ofrecen opciones de consulta que te permiten buscar no sólo en documentos, sino también en nombres de usuario.

Sin embargo, hay algo que es fundamental: debes utilizar una herramienta que te permita buscar rápidamente. Una función de búsqueda incluida en la aplicación hace que sea sencillo buscar archivos y obtener una vista previa de ellos sin salir de la aplicación.

Docsie te permite disponer de una navegación con búsqueda dinámica para acceder fácilmente a la información.

Esforzarse constantemente por mejorar y actualizar

Crear y utilizar documentos es difícil porque rápidamente son olvidados por las personas que los generaron o se beneficiaron de ellos. Los documentos también se enfrentan a una serie de retos a lo largo de su viaje.

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

Así que asegúrese de revisar su documentación antigua y realizar mejoras, además de animar a sus colegas a hacer lo mismo de vez en cuando. Docsie le permite crear actualizaciones a través de nuestro avanzado sistema de versionado, que es sencillo y fácil de hacer.

Reflexiones finales:

¿Quieres saber más sobre cómo escribir documentación eficaz? Para los profesionales de la documentación de software, hay un montón de blogs e información aquí.