Good practices to develop free and open Software: Documentation

La documentation is and should be a fundamental part of the creative process and planning of all human activity, and more in the technological field, especially in the area of Software development.

El purpose of all documentation it must be Him teach third parties (users, administrators, maintainers, or other developers), who are not usually familiar with the product (code, application or system), how is it created its structure, its operation and even if it is possible, the reason for its creation and its way of design and operation.

Furthermore, in the specific case of Free Software documentation is vital, since it allows to fully guarantee the knowledge transfer and empowerment necessary for the satisfactory fulfillment of the 4 freedoms promoted by it, which are:

• 0: The freedom to run the program however you want, for any purpose.
• 1: The freedom to access and study a program, and change or adapt it for your own benefit.
• 2: The freedom to share or redistribute copies to spread the same and / or help others.
• 3: The freedom to distribute copies of your modified versions to third parties.

A good documentation makes it possible, therefore, that the created product:

• It is used correctly, and it is more easily taught and learned.
• Be thoroughly understood by those who wish to modify it to improve or adapt it.
• Be shared and received with more confidence, among all possible acquaintances and strangers.
• Have a better mass among the public.

Good practices: Documentation

Fundamentals

In the case of Development of Free Software and Open Source, generally, main users of the documentation relative to product design, are those that are or will be, the responsible for maintenance of the same. And without good or no documentation, the only viable alternative is to directly explore it, to achieve understand its design and function.

Not creating good documentation when it comes to develop Free Software, Open Source or any other type of software, is to send to its possible recipients (users, administrators, maintainers, or other developers) to find a way through a jungle without a map or a compass.

Create good documentation for each Free Software, Open Source it is also beneficial, since, although documenting has a costThe investment, if done correctly, is worth it. Because, the world of Software is full of stories about legacy codes old or current programs, applications or systems, that only few people dare to touch, because almost no one understands. Programmers focus on creating code and not documenting it correctly and completely. And this must be remedied.

Good practices on documentation in README text files

In the case of Free Software and Open Source, documentation is often restricted to text files, when it is created by individuals or small groups of programmers or communities. But, even creating a simple documentation using a simple text file README.md (or .txt) you can have your best or good practices, tips or useful guide of creation to bring to third parties the most complete and detailed information necessary about the creation.

For our article, we have taken the Best Practices conceived and disclosed by the "Code for Development Initiative" of the Interamerican Development Bank, which in summary tells us that good documentation based on a text file README.md (or .txt) It must be structured as follows:

Recommended README file structure

• Description and context: Section where the functionalities must be described, the context where it was developed and the development problems it helped to solve.
• User's Guide: Section where instructions to the end user on how to start using the digital tool should be mentioned.
• Installation guide: Section where the installation instructions to reuse and configure the digital tool should be mentioned. This section is intended for developers.
• Writers Section where credits must be given to the collaborators of the tool.
• License for the tool code: Section where the permissions granted to third parties to reuse the digital tool must be specified.
• License for the documentation of the tool: Section where the type of license contained in the documentation created must be mentioned.

In these good practice, they also recommend adding to the README file documentation to make it more complete, the following sections:

• How to contribute: Section that explains to new developers the process to contribute to projects.
• Code of conduct: Section that explains the code of conduct establishes the social norms, rules and responsibilities that individuals and organizations must follow when interacting in any way with the digital tool or their community.
• Badges: Section showing the badges (small images embedded in the README.md) that specify in a readable and concise way the state of the tool.
• Version: Section that indicates a list of the versions of the digital tool and the functionalities added to each version.
• Acknowledgments: Section that contains the acknowledgments to other people or organizations that have contributed in some way to the project.

To expand this information, on the Best Practices in terms of Documentation for the development of Free software, by the "Code for Development Initiative" of the Interamerican Development Bank you can click on the following link: Documentation - Guide for publishing digital tools. And in other publications we will explore the part referring to good practice on evaluation and licensing of the Free and Open Software themselves.

Conclusion

We hope that this "useful little post" the «Buenas prácticas» in the field of «documentación» to create when developing «Software libre y abierto», is of great interest and utility, for the entire «Comunidad de Software Libre y Código Abierto» and of great contribution to the diffusion of the wonderful, gigantic and growing ecosystem of applications of and for «GNU/Linux».

And for more information, always do not hesitate to visit any Online library as OpenLibra y jedit to read books (PDFs) on this topic or others knowledge areas. For now, if you liked this «publicación», don't stop sharing it with others, in your Favorite websites, channels, groups, or communities of social networks, preferably free and open as Mastodon, or secure and private like Telegram.

Or simply visit our home page at DesdeLinux or join the official Channel Telegram from DesdeLinux to read and vote for this or other interesting publications on «Software Libre», «Código Abierto», «GNU/Linux» and other topics related to «Informática y la Computación», and the «Actualidad tecnológica».