Gute Praktiken zur Entwicklung freier und offener Software: Dokumentation

La Dokumentation ist und sollte ein grundlegender Bestandteil der kreativer Prozess und Planung aller menschlichen Aktivitäten und mehr im technologischen Bereich, insbesondere im Bereich Software-Entwicklung.

El Zweck aller Unterlagen es muss er sein Unterrichten von Dritten (Benutzer, Administratoren, Betreuer oder andere Entwickler), die normalerweise nicht mit dem vertraut sind Produkt (Code, Anwendung oder System), wie entsteht es seine Struktur, seine Funktionsweise und selbst wenn möglich, den Grund für seine Entstehung und seine Art zu entwerfen und zu betreiben.

Darüber hinaus im konkreten Fall von Freie Software Dokumentation ist wichtig, da es erlaubt, die Wissenstransfer und Empowerment notwendig für die zufriedenstellende Erfüllung der 4 Freiheiten gefördert von ihm, die sind:

• 0: Die Freiheit, das Programm für jeden Zweck auszuführen, wie Sie möchten.
• 1: Die Freiheit, auf ein Programm zuzugreifen, es zu studieren und es zu Ihrem eigenen Vorteil zu ändern oder anzupassen.
• 2: Die Freiheit, Kopien zu teilen oder weiterzugeben, um sie zu verbreiten und / oder anderen zu helfen.
• 3: Die Freiheit, Kopien Ihrer geänderten Versionen an Dritte zu verteilen.

Eine gute Dokumentation ermöglicht es daher, dass das erstellte Produkt:

• Es wird richtig verwendet und ist leichter zu lehren und zu lernen.
• Seien Sie gründlich verstanden von denen, die es modifizieren möchten, um es zu verbessern oder anzupassen.
• Mit mehr Vertrauen unter allen potenziellen Bekannten und Fremden geteilt und empfangen werden.
• Haben Sie eine bessere Masse in der Öffentlichkeit.

Gute Praktiken: Dokumentation

Grundlage

Im Fall von Entwicklung von Freier Software und Open Source, allgemein, Hauptbenutzer der Dokumentation in Bezug auf das Produktdesign sind diejenigen, die sind oder sein werden, die verantwortlich für die Wartung von dem selben. Und ohne gute oder keine Dokumentation besteht die einzig praktikable Alternative darin, sie direkt zu untersuchen, um sie zu erreichen verstehen sein Design und seine Funktion.

Keine gute Dokumentation erstellen, wenn es darum geht Entwickeln Sie Freie Software, Open Source oder jede andere Art von Software ist an ihre möglichen Empfänger zu senden (Benutzer, Administratoren, Betreuer oder andere Entwickler) einen Weg durch einen Dschungel ohne Karte oder Kompass zu finden.

Erstellen Sie für jeden eine gute Dokumentation Freie Software, Open Source es ist auch vorteilhaft, obwohl, obwohl Dokumentation hat KostenDie Investition lohnt sich, wenn sie richtig getätigt wird. Weil die Welt von Software ist voller Geschichten über Legacy-Codes alte oder aktuelle Programme, Anwendungen oder Systeme, die nur wenige Menschen zu berühren wagen, weil fast niemand versteht. Programmierer konzentrieren sich darauf, Code zu erstellen und ihn nicht korrekt und vollständig zu dokumentieren. Und das muss behoben werden.

Gute Praktiken zur Dokumentation in README-Textdateien

Im Fall von Freie Software und Open SourceDie Dokumentation ist häufig auf Textdateien beschränkt, wenn sie von Einzelpersonen oder kleinen Gruppen von Programmierern oder Communitys erstellt wird. Aber bis zum Erstellen einer einfachen Dokumentation mit einem einfachen Textdatei README.md (oder .txt) du kannst deine haben Best oder Good Practices, Tipps oder nützliche Anleitungen zur Erstellung, um Dritten die umfassendsten und detailliertesten Informationen zu liefern, die für die Erstellung erforderlich sind.

Für unseren Artikel haben wir die genommen Gute Praktiken konzipiert und offenbart von der "Kodex für Entwicklungsinitiative" Restaurants Interamerikanische Entwicklungsbank, was uns zusammenfassend sagt, dass eine gute Dokumentation auf a Textdatei README.md (oder .txt) Es muss wie folgt aufgebaut sein:

Empfohlene README-Dateistruktur

• Beschreibung und Kontext: Abschnitt, in dem Sie die Funktionen, den Kontext, in dem sie entwickelt wurden, und die Entwicklungsprobleme, die sie gelöst haben, beschreiben müssen.
• Bedienungsanleitung: In diesem Abschnitt sollten Anweisungen für den Endbenutzer zum Starten des digitalen Tools erwähnt werden.
• Installationsanleitung: Abschnitt, in dem die Installationsanweisungen zur Wiederverwendung und Konfiguration des digitalen Tools erwähnt werden sollten. Dieser Abschnitt richtet sich an Entwickler.
• Autoren Abschnitt, in dem den Mitarbeitern des Tools Credits gewährt werden müssen.
• Lizenz für den Toolcode: Abschnitt, in dem die Berechtigungen angegeben werden, die Dritten zur Wiederverwendung des digitalen Tools erteilt wurden.
• Lizenz für die Werkzeugdokumentation: Abschnitt, in dem die Art der Lizenz in der erstellten Dokumentation angegeben werden muss.

In diesen gute Praxisempfehlen sie auch das Hinzufügen zum README-Dateidokumentation Um es zu vervollständigen, die folgenden Abschnitte:

• So tragen Sie bei: Abschnitt, der neuen Entwicklern den Prozess erklärt, um zu Projekten beizutragen.
• Verhaltenskodex: In einem Abschnitt, in dem der Verhaltenskodex erläutert wird, werden die sozialen Normen, Regeln und Verantwortlichkeiten festgelegt, denen Einzelpersonen und Organisationen folgen müssen, wenn sie in irgendeiner Weise mit dem digitalen Tool oder ihrer Community interagieren.
• Abzeichen: Abschnitt mit den Ausweisen (kleine Bilder, die in README.md eingebettet sind), die den Status des Tools lesbar und präzise angeben.
• Version: Abschnitt, der eine Liste der Versionen des digitalen Tools und der Funktionen enthält, die jeder Version hinzugefügt wurden.
• Danksagung: Abschnitt, der die Danksagungen an andere Personen oder Organisationen enthält, die in irgendeiner Weise zum Projekt beigetragen haben.

Um diese Informationen zu erweitern, klicken Sie auf Gute Praktiken in Angelegenheiten von Dokumentation für die Entwicklung von Kostenlose Software, bis zum "Kodex für Entwicklungsinitiative" Restaurants Interamerikanische Entwicklungsbank Sie können auf folgenden Link klicken: Dokumentation - Leitfaden zum Veröffentlichen digitaler Tools. In anderen Veröffentlichungen werden wir den Teil untersuchen, auf den wir uns beziehen gute Praxis auf Evaluierung und Lizenzierung Restaurants Freie und offene Software sich.

Fazit

Wir hoffen es dies "hilfreicher kleiner Beitrag" auf «Buenas prácticas» im Bereich der «documentación» bei der Entwicklung zu schaffen «Software libre y abierto»ist von großem Interesse und Nutzen für das Ganze «Comunidad de Software Libre y Código Abierto» und von großem Beitrag zur Verbreitung des wunderbaren, gigantischen und wachsenden Ökosystems von Anwendungen von und für «GNU/Linux».

Und für weitere Informationen zögern Sie nicht immer, eine zu besuchen Online-Bibliothek als OpenLibra y jedit zu lesen Bücher (PDFs) zu diesem oder anderen Themen Wissensbereiche. Fürs Erste, wenn dir das gefallen hat «publicación», Hör nicht auf, es zu teilen mit anderen in deinem Lieblingswebsites, -kanäle, -gruppen oder -gemeinschaften von sozialen Netzwerken, vorzugsweise frei und offen als Mastodonoder sicher und privat wie Telegram.

Oder besuchen Sie einfach unsere Homepage unter DesdeLinux oder trete dem offiziellen Kanal bei Telegramm von DesdeLinux zu lesen und für diese oder andere interessante Publikationen zu stimmen «Software Libre», «Código Abierto», «GNU/Linux» und andere Themen im Zusammenhang mit «Informática y la Computación»Und das «Actualidad tecnológica».