Bonnes pratiques pour développer des logiciels libres et ouverts: documentation

La documentation est et devrait être un élément fondamental de la processus créatif et planification de toute activité humaine, et plus encore dans le domaine technologique, en particulier dans le domaine Développement de logiciels.

El but de toute la documentation ça doit être lui enseigner à des tiers (utilisateurs, administrateurs, mainteneurs ou autres développeurs), qui ne sont généralement pas familiers avec le produit (code, application ou système), comment est-il créé sa structure, son fonctionnement et même si possible, la raison de sa création et son mode de conception et de fonctionnement.

De plus, dans le cas spécifique de La documentation du logiciel libre est vitale, car il permet de garantir pleinement la transfert de connaissances et autonomisation nécessaire à l'accomplissement satisfaisant de la 4 libertés promu par elle, qui sont:

• 0: La liberté d'exécuter le programme comme vous le souhaitez, dans n'importe quel but.
• 1: La liberté d'accéder et d'étudier un programme, et de le modifier ou de l'adapter à votre avantage.
• 2: La liberté de partager ou de redistribuer des copies pour les diffuser et / ou aider les autres.
• 3: La liberté de distribuer des copies de vos versions modifiées à des tiers.

Une bonne documentation permet donc que le produit créé:

• Il est utilisé correctement et il est plus facile à enseigner et à apprendre.
• Soyez bien compris par ceux qui souhaitent le modifier pour l'améliorer ou l'adapter.
• Soyez partagé et reçu avec plus de confiance, entre toutes les connaissances potentielles et les étrangers.
• Ayez une meilleure masse parmi le public.

Bonnes pratiques: documentation

Notions de base

Dans le cas d' Développement de logiciels libres et open source, généralement, principaux utilisateurs de la documentation par rapport à la conception du produit, sont ceux qui sont ou seront responsable de la maintenance du même. Et sans bonne ou pas de documentation, la seule alternative viable est de l'explorer directement, pour atteindre comprendre sa conception et sa fonction.

Ne pas créer une bonne documentation en ce qui concerne développer des logiciels libres, open source ou tout autre type de logiciel, est à envoyer à ses éventuels destinataires (utilisateurs, administrateurs, mainteneurs ou autres développeurs) pour trouver un chemin à travers une jungle sans carte ni boussole.

Créez une bonne documentation pour chacun Logiciel libre, Open Source il est également bénéfique, car, bien que la documentation a un coûtL'investissement, s'il est fait correctement, en vaut la peine. Parce que, le monde de Logiciels est plein d'histoires sur codes hérités programmes, applications ou systèmes anciens ou actuels, que peu de gens osent toucher, car presque personne ne comprend. Les programmeurs se concentrent sur la création de code et ne le documentent pas correctement et complètement. Et cela doit être corrigé.

Bonnes pratiques sur la documentation dans les fichiers texte README

Dans le cas d' Logiciel libre et open source, la documentation est souvent limitée aux fichiers texte, lorsqu'elle est créée par des individus ou de petits groupes de programmeurs ou de communautés. Mais, jusqu'à créer une documentation simple en utilisant un simple fichier texte README.md (ou .txt) vous pouvez avoir votre meilleures ou bonnes pratiques, astuces ou guide de création utile pour apporter à des tiers les informations les plus complètes et détaillées nécessaires sur ce qui a été créé.

Pour notre article, nous avons pris le Les bonnes pratiques conçu et divulgué par le "Code pour l'initiative de développement » de la Banque Interaméricaine de Développement, qui en résumé nous dit qu'une bonne documentation basée sur un fichier texte README.md (ou .txt) Il doit être structuré comme suit:

Structure de fichier README recommandée

• Description et contexte: Section où les fonctionnalités doivent être décrites, le contexte dans lequel elle a été développée et les problèmes de développement qu'elle a permis de résoudre.
• Guide de l'utilisateur: Section où les instructions à l'utilisateur final sur la façon de commencer à utiliser l'outil numérique doivent être mentionnées.
• Guide d'installation: Section où les instructions d'installation pour réutiliser et configurer l'outil numérique doivent être mentionnées. Cette section est destinée aux développeurs.
• auteurs Section où les crédits doivent être attribués aux collaborateurs de l'outil.
• Licence pour le code de l'outil: Section où les autorisations accordées à des tiers pour réutiliser l'outil numérique doivent être spécifiées.
• Licence pour la documentation de l'outil: Section où le type de licence contenu dans la documentation créée doit être mentionné.

Dans ces bonnes pratiques, ils recommandent également d'ajouter à la Documentation du fichier README pour le rendre plus complet, les sections suivantes:

• Comment contribuer: Section qui explique aux nouveaux développeurs le processus de contribution aux projets.
• Code de conduite: La section qui explique le code de conduite établit les normes sociales, les règles et les responsabilités que les individus et les organisations doivent respecter lorsqu'ils interagissent de quelque manière que ce soit avec l'outil numérique ou leur communauté.
• Badges: Section présentant les badges (petites images intégrées dans le README.md) qui spécifient de manière lisible et concise l'état de l'outil.
• Version: Section qui indique une liste des versions de l'outil numérique et des fonctionnalités ajoutées à chaque version.
• Remerciements: Section qui contient les remerciements à d'autres personnes ou organisations qui ont contribué d'une manière ou d'une autre au projet.

Pour développer ces informations, sur le Les bonnes pratiques en matière de documentation pour le développement de logiciels gratuits, par le "Code pour l'initiative de développement » de la Banque Interaméricaine de Développement vous pouvez cliquer sur le lien suivant: Documentation - Guide de publication d'outils numériques. Et dans d'autres publications, nous explorerons la partie faisant référence à bonnes pratiques sobre la évaluation et licence de la Logiciels libres et ouverts se.

Conclusion

Attendre cette "petit message utile » sur «Buenas prácticas» dans le domaine de «documentación» à créer lors du développement «Software libre y abierto», est d'un grand intérêt et d'une grande utilité, pour l'ensemble «Comunidad de Software Libre y Código Abierto» et d'une grande contribution à la diffusion de l'écosystème merveilleux, gigantesque et croissant d'applications de et pour «GNU/Linux».

Et pour plus d'informations, n'hésitez pas toujours à visiter Bibliothèque en ligne comme OpenBalance y Jedit pour lire livres (PDF) sur ce sujet ou sur d'autres domaines de connaissances. Pour l'instant, si vous avez aimé ça «publicación», n'arrêtez pas de le partager avec les autres, dans votre Sites Web, chaînes, groupes ou communautés favoris des réseaux sociaux, de préférence gratuits et ouverts au Mastodonte, ou sécurisé et privé comme Telegram.

Ou visitez simplement notre page d'accueil à DesdeLinux ou rejoignez la chaîne officielle Télégramme de DesdeLinux lire et voter pour cette publication ou d'autres publications intéressantes sur «Software Libre», «Código Abierto», «GNU/Linux» et d'autres sujets liés à «Informática y la Computación»Et l' «Actualidad tecnológica».