Buenas prácticas para desarrollar Software libre y abierto: Documentación

La documentación es y debe ser una parte fundamental del proceso creativo y planificador de toda actividad humana, y más en el ámbito tecnológico, sobre todo en el área del Desarrollo del Software.

El propósito de toda documentación debe ser, el enseñar a terceros (usuarios, administradores, mantenedores, u otros desarrolladores), que no suelen estar familiarizados con el producto (código, aplicación o sistema), cómo está creada su estructura, su funcionamiento y hasta si es posible, el por qué de su creación y su forma de diseño y funcionamiento.

Además, en el caso específico del Software Libre la documentación es vital, ya que la misma permite garantizar plenamente la transferencia de conocimiento y el empoderamiento necesario para que se cumplan satisfactoriamente las 4 libertades promovidas por el mismo, las cuales son:

• 0: La libertad de ejecutar el programa como se desee, con cualquier propósito.
• 1: La libertad de acceder y estudiar un programa, y cambiarlo o adaptarlo para el beneficio propio.
• 2: La libertad de compartir o redistribuir copias para difundir el mismo y/o ayudar a otros.
• 3: La libertad de distribuir copias de sus versiones modificadas a terceros.

Una buena documentación hace posible, por ende, que el producto creado:

• Se use correctamente, y se enseñe y aprenda más fácilmente.
• Sea entendido a profundidad, por aquellos que deseen modificarlo para mejorarlo u adaptarlo.
• Se comparta y sea recibido con más confianza, entre todos los posibles conocidos y desconocidos.
• Tenga una mejor masificación entre el público.

Buenas prácticas: Documentación

Fundamentos

En el caso del Desarrollo del Software Libre y Código Abierto, por lo general, los principales usuarios de la documentación relativa al diseño del producto, son aquellos que son o serán, los responsables del mantenimiento del mismo. Y sin una buena o nula documentación, la única alternativa viable es explorar directamente el mismo, para lograr entender su diseño y funcionamiento.

No crear una buena documentación a la hora de desarrollar Software Libre, Código Abierto o cualquier otro tipo de software, es enviar a sus posibles destinatarios (usuarios, administradores, mantenedores, u otros desarrolladores) a buscar un camino a través de una selva sin mapa ni brújula.

Crear una buena documentación para cada Software Libre, Código Abierto también es beneficioso, ya que, aunque documentar tiene un coste, la inversión, si se hace correctamente, vale la pena. Debido a que, el mundo del Software está repleto de historias sobre códigos heredado de viejos o actuales programas, aplicaciones o sistemas, que solo pocas personas se atreven a tocar, porque casi nadie lo entiende. Los programadores se enfocan en crear código y no en documentarlo correcta y completamente. Y esto debe ser subsanado.

Buenas prácticas sobre documentación en archivos de textos README

En el caso del Software Libre y Código Abierto, muchas veces la documentación suele restringirse a archivos de texto, cuando el mismo es creado por individualidades o pequeños grupos de programadores o comunidades. Pero, hasta crear una documentación sencilla mediante un sencillo archivo de texto README.md (o .txt) puede tener sus mejores o buenas prácticas, consejos o guía útil de creación para llevar a terceros la más completa y detallada información necesaria sobre lo creado.

Para nuestro artículo, hemos tomado las Buenas prácticas concebidas y divulgadas por la “Iniciativa Código para el Desarrollo” del Banco Interamericano de Desarrollo, que de forma resumida nos dice que una buena documentación basada en un archivo de texto README.md (o .txt) debe estar estructurada de la siguiente manera:

Estructura recomendada del archivo README

• Descripción y contexto: Sección donde se debe describir las funcionalidades, el contexto donde fue desarrollado y los problemas de desarrollo que ayudó a resolver.
• Guía de usuario: Sección donde se deben mencionar las instrucciones al usuario final sobre cómo empezar a usar la herramienta digital.
• Guía de instalación: Sección donde se deben mencionar las instrucciones de instalación para reutilizar y configurar la herramienta digital. Esta sección está dirigida a desarrolladores.
• Autores Sección donde se deben dar créditos a los colaboradores de la herramienta.
• Licencia para el código de la herramienta: Sección donde se deben especificar los permisos que se otorgan a terceros para reutilizar la herramienta digital.
• Licencia para la documentación de la herramienta: Sección donde se debe mencionar el tipo de licencia que lleva la documentación creada.

En estas buenas prácticas, también recomiendan añadir a la documentación del archivo README para hacerla más completa, las siguientes secciones:

• Cómo contribuir: Sección que explica a nuevos desarrolladores el proceso para contribuir a proyectos.
• Código de conducta: Sección que explica el código de conducta establece las normas sociales, reglas y responsabilidades que los individuos y organizaciones deben seguir al interactuar de alguna manera con la herramienta digital o su comunidad.
• Insignias (badges): Sección que muestra las insignias (pequeñas imágenes incrustadas en el README.md) que especifican de una manera legible y concisa el estado de la herramienta.
• Versión: Sección que indica un listado de las versiones de la herramienta digital y las funcionalidades añadidas a cada versión.
• Reconocimientos: Sección que contiene los reconocimientos a otras personas u organizaciones que hayan contribuido de alguna forma al proyecto.

Para ampliar dicha información, sobre las Buenas prácticas en materia de Documentación para el desarrollo del Software Libre, por parte de la “Iniciativa Código para el Desarrollo” del Banco Interamericano de Desarrollo se puede hacer clic en el siguiente enlace: Documentación – Guía para publicar herramientas digitales. Y en otras publicaciones exploraremos la parte referente a las buenas prácticas sobre la evaluación y licenciamiento del Software Libre y Abierto de ellos mismos.

Conclusión

Esperamos que esta “pequeña y útil publicación” sobre las «Buenas prácticas» en el ámbito de la «documentación» a crear a la hora de desarrollar «Software libre y abierto», sea de mucho interés y utilidad, para toda la «Comunidad de Software Libre y Código Abierto» y de gran contribución a la difusión del maravilloso, gigantesco y creciente ecosistema de aplicaciones de y para «GNU/Linux».

Y para mayor información, no dudes siempre en visitar cualquier Biblioteca en línea como OpenLibra y JedIT para leer libros (PDFs) sobre este tema u otras áreas del conocimiento. Por ahora, si te ha gustado esta «publicación», no dejes de compartirla con otros, en tus sitios web, canales, grupos o comunidades favoritas de redes sociales, preferiblemente libres y abiertas como Mastodon, o seguras y privadas como Telegram.

O simplemente, visita nuestra página de inicio en DesdeLinux o únete al Canal oficial de Telegram de DesdeLinux para leer y votar por esta u otras interesantes publicaciones sobre «Software Libre», «Código Abierto», «GNU/Linux» y demás temas relacionados con la «Informática y la Computación», y la «Actualidad tecnológica».