Introducción

Imagina que te has topado con un proyecto de código abierto que se alinea perfectamente con tus intereses. Estás ansioso por usarlo o contribuir a él, pero ¿dónde debes empezar? La respuesta está en la documentación del proyecto.

Ahora piensa en la Documentación de Código Abierto como una guía para ayudar a un usuario a sacar el máximo provecho de un proyecto. Guía al usuario a través de las complejidades del proyecto, al mismo tiempo que le ayuda a comprender los principios fundamentales del proyecto, cómo usarlo y cómo realizar sus contribuciones.

En este artículo, examinaremos la documentación de código abierto, los tipos de documentación de código abierto, discutiremos la importancia, las mejores prácticas para crearla y finalmente herramientas para agilizar el proceso de creación de una documentación de código abierto.

¿Qué es exactamente la Documentación de Código Abierto?

Lo primero es lo primero, definamos “código abierto”. Código abierto en términos simples significa un tipo de software cuyo código fuente está disponible de forma gratuita al público para inspeccionar, modificar, mejorar y distribuir. Por ejemplo: sistema operativo Linux, navegador web Firefox, MongoDB, etc.

Ahora, la Documentación de Código Abierto se refiere a los materiales escritos asociados con el software de código abierto. Proporciona información sobre el uso, la funcionalidad y el mantenimiento de los productos. Incluye detalles e información sobre las características del software, la configuración de la instalación y el uso. Esta documentación suele estar disponible para el público junto con el código fuente.

La Documentación de Código Abierto sirve como un recurso completo para los desarrolladores, usuarios y contribuyentes, proporcionando información esencial sobre el propósito, características y uso del proyecto. Al principio, los proyectos de Código Abierto pueden parecer abrumadores, pero con la ayuda de una buena documentación, permite a los usuarios y contribuyentes comprender el proyecto.

Tipos de Documentación de Código Abierto

Los proyectos de Código Abierto suelen tener 3 tipos de documentación. Cada uno de ellos satisface necesidades específicas. Incluyen Documentación Técnica, Documentación de Producto y Pautas.

Documentación Técnica : Esta documentación es para desarrolladores. Profundiza en la base de código, explica la API y demuestra cómo utilizar la interfaz de programación del proyecto. También incluye documentos introductorios para el proyecto, pautas para desarrolladores que trabajan con el proyecto e instrucciones para configurar el entorno de desarrollo. La Documentación de API, las guías de desarrollo y el README son excelentes ejemplos de Documentación Técnica.

Documentación de Producto : Esta documentación está dirigida a los usuarios del proyecto. Incluyen manuales de usuario, guías de inicio rápido, guías de instalación, guías de resolución de problemas, preguntas frecuentes, etc. Se centran principalmente en la experiencia del usuario y guían a los usuarios para que comprendan los proyectos, sus características y cómo utilizar el proyecto.

Pautas : Esta documentación está hecha a medida para los contribuyentes al proyecto. Ayudan a los contribuyentes a comprender cómo navegar por el proyecto. Los tipos comunes de pautas de proyectos de Código Abierto son:

Guías de contribución: Son realmente importantes ya que explican cómo contribuir al proyecto, incluyendo envíos de código e informes/correcciones de errores.
Guías de estilo: proporciona información sobre el estilo preferido, formato y convenciones de nomenclatura. Asegura calidad y consistencia en el código y las contribuciones.
Código de conducta: establece el comportamiento esperado de los contribuyentes y miembros de la comunidad.

Importancia de la documentación de código abierto

Una buena documentación es de suma importancia tanto para el usuario del proyecto como para el contribuyente al proyecto. Veamos cómo una buena documentación ayuda a los usuarios y contribuyentes de un proyecto de código abierto.

Para los usuarios:

Experiencia de usuario mejorada: Una buena documentación ayuda al usuario a comprender cómo utilizar el proyecto de manera efectiva y sacarle el máximo provecho. Proporciona una solución más rápida a los problemas que un usuario pueda encontrar al utilizar el proyecto.
Adopción y uso más sencillos del software: Una documentación clara y concisa facilita la comprensión de las características y funcionalidades del software. Reduce la curva de aprendizaje y hace que el software sea más accesible para una gama más amplia de usuarios.
Resolución de problemas: Una documentación detallada puede ayudar a los usuarios a solucionar problemas y encontrar soluciones de manera independiente. Esto disminuye la dependencia del personal de soporte y mejora la experiencia general del usuario.
Reducción de costos de soporte: Una buena documentación puede ayudar a minimizar la cantidad de preguntas de soporte, ahorrando tiempo y recursos tanto a los usuarios como a los desarrolladores.

Para colaboradores:

Comprensión más clara del proyecto : Para poder contribuir a un proyecto, es necesario comprenderlo. Contar con una buena documentación ayuda al lector a entender el proyecto y cómo empezar con su contribución.
Onboarding efectivo : Una buena documentación facilita un proceso de integración fluido para los colaboradores. Les ayuda a familiarizarse más con la base de código del proyecto, el flujo de trabajo y los detalles necesarios para realizar sus contribuciones.
Colaboración mejorada: La documentación clara y concisa crea un terreno común para los colaboradores, asegurando que todos entiendan los objetivos del proyecto, la arquitectura y las normas de codificación. Los colaboradores pueden obtener fácilmente la información que necesitan para llevar a cabo sus tareas, reduciendo retrasos y malentendidos.

Mejores prácticas para lograr una buena Documentación

Según lo discutido hasta ahora, se puede ver que escribir una buena documentación para tu proyecto de código abierto es realmente crucial. Para poder lograr una buena documentación que satisfaga las necesidades de tus usuarios y colaboradores en el proyecto, aquí tienes algunas cosas que hacer.

Escribe de manera clara y concisa para permitir que tus lectores entiendan fácilmente lo que estás presentando. Es importante evitar el uso de tecnicismos complejos que puedan confundir a tus lectores, ya que la esencia de la documentación es mejorar la experiencia del usuario

Organiza tu documentación de manera estructurada y patrón. Para lograr esto, implica organizar tu información de manera lógica utilizando encabezados, subencabezados y viñetas. Tu documentación debe seguir un patrón estructurado, todo debería fluir bien de arriba abajo y debería ser fácil para los lectores seguir
Escribe teniendo en cuenta las necesidades del usuario. Es importante ponerte en su lugar, tu documentación debe ser un recurso útil, no una barrera de entrada. Explica los conceptos de la forma más clara posible; no des nada por sentado. Puedes incluir fragmentos de código para ayudar a explicar conceptos específicos, anticipar preguntas comunes y proporcionar soluciones/respuestas directas.
Mantén tu documentación actualizada actualizándola siempre que se realicen cambios en el proyecto. Tu documentación debe enviarse junto al código, a medida que se actualiza el código base, la documentación también debe actualizarse.
Proporciona instrucciones claras sobre cómo contribuir al proyecto. De esta forma, las personas que deseen contribuir pueden orientarse en el proyecto y realizar sus cambios fácilmente.
Revise errores, inconsistencias o información desactualizada. También solicita comentarios de tus usuarios, esto ayuda a mejorar la documentación.
Por último, aprovecha las herramientas que pueden ayudar a lograr una buena documentación. Hay muchas herramientas disponibles que puedes utilizar para

Herramientas para crear una buena documentación

Como se mencionó anteriormente, hay muchas herramientas que puedes utilizar para crear una buena documentación que los usuarios puedan revisar y entender fácilmente. Aquí tienes algunas de ellas.

Sphinx : una herramienta popular para crear documentación técnica, especialmente para proyectos de Python. Admite varios formatos de salida (HTML, PDF, LaTeX) y tiene un rico ecosistema de extensiones.
Doxygen : una herramienta para generar documentación de API a partir de comentarios en el código fuente. Admite varios lenguajes de programación y puede producir documentación en HTML, LaTeX y otros formatos.
MkDocs: un generador de documentación simple, rápido y configurable que utiliza Markdown para escribir contenido. Es ideal para proyectos más pequeños.
Read the Docs: una plataforma de alojamiento para documentación construida con Sphinx o MkDocs. Simplifica la documentación de software mediante la construcción, versionado y alojamiento de tus documentos.
Git : Git te permite rastrear cambios en tu documentación a lo largo del tiempo. Esto significa que puedes revertir fácilmente a versiones anteriores si es necesario, y también ayuda a prevenir eliminaciones accidentales. Ayuda en las actualizaciones continuas de la documentación.

Puedes revisar la documentación de cada herramienta para tener una comprensión profunda de cómo funcionan y cómo empezar a usarlas.

Conclusión

Para concluir, una buena documentación determina cuán bien se entiende y utiliza un proyecto. Es esencial tener una documentación clara y concisa que atienda las necesidades de todos los que buscan utilizar un proyecto de Código Abierto.

Del artículo, se puede ver que al invertir tiempo y esfuerzo en crear una documentación exhaustiva, bien estructurada y accesible, no solo mejoras la experiencia del usuario, sino que también aseguras la sostenibilidad de tu proyecto.

La próxima vez que encuentres un proyecto de código abierto que llame tu atención, no dudes en investigar; la documentación será tu guía para usar o contribuir al proyecto.

Recursos

https://opensource.googleblog.com/2018/10/building-great-open-source-documentation.html

https://opensource.com/article/20/3/documentation

https://herothemes.com/blog/best-documentation-tools/