Goede praktijken om gratis en open software te ontwikkelen: documentatie

La documentatie is en zou een fundamenteel onderdeel moeten zijn van het creatief proces en planning van alle menselijke activiteit, en meer op technologisch gebied, vooral op het gebied van Software ontwikkeling.

El doel van alle documentatie Hij moet het zijn leren derden (gebruikers, beheerders, beheerders of andere ontwikkelaars), die meestal niet bekend zijn met de product (code, applicatie of systeem), hoe is het gemaakt zijn structuur, zijn werking en zelfs indien mogelijk, de reden voor het ontstaan ​​en de manier van ontwerpen en gebruiken.

Bovendien, in het specifieke geval van Vrije Software-documentatie is essentieel, omdat het het mogelijk maakt om de kennisoverdracht en empowerment noodzakelijk voor de bevredigende vervulling van de 4 vrijheden erdoor gepromoot, namelijk:

• 0: De vrijheid om het programma uit te voeren zoals u dat wilt, voor elk doel.
• 1: De vrijheid om toegang te krijgen tot een programma en het te studeren, en het voor uw eigen voordeel te wijzigen of aan te passen.
• 2: De vrijheid om kopieën te delen of opnieuw te verspreiden om ze te verspreiden en / of anderen te helpen.
• 3: De vrijheid om kopieën van uw gewijzigde versies te verspreiden onder derden.

Een goede documentatie maakt het daarom mogelijk dat het gemaakte product:

• Het wordt correct gebruikt en het wordt gemakkelijker onderwezen en geleerd.
• Goed begrepen worden door degenen die het willen wijzigen om het te verbeteren of aan te passen.
• Met meer vertrouwen gedeeld en ontvangen worden onder alle potentiële kennissen en vreemden.
• Zorg voor een betere massa onder het publiek.

Goede praktijken: documentatie

Fundamentals

Bij Ontwikkeling van vrije software en open source, over het algemeen, belangrijkste gebruikers van de documentatie gerelateerd aan productontwerp, zijn degenen die zijn of zullen zijn, de verantwoordelijk voor onderhoud van hetzelfde. En zonder goede of geen documentatie is het enige haalbare alternatief om het direct te verkennen, om te bereiken begrijp zijn ontwerp en functie.

Geen goede documentatie maken als het gaat om ontwikkelen van vrije software, open source of elk ander type software, is om naar de mogelijke ontvangers te verzenden (gebruikers, beheerders, beheerders of andere ontwikkelaars) om een ​​weg door een jungle te vinden zonder kaart of kompas.

Maak voor elk een goede documentatie Gratis software, open source het is ook gunstig, aangezien, hoewel documenteren heeft kostenDe investering is, mits correct gedaan, de moeite waard. Omdat de wereld van Software staat vol met verhalen over oude codes van oude of huidige programma's, applicaties of systemen, die maar weinig mensen durven aan te raken, omdat bijna niemand het begrijpt. Programmeurs richten zich op het maken van code en het niet correct en volledig documenteren ervan. En dit moet worden verholpen.

Goede praktijken met betrekking tot documentatie in README-tekstbestanden

Bij Gratis software en open sourceis documentatie vaak beperkt tot tekstbestanden, wanneer deze is gemaakt door individuen of kleine groepen programmeurs of gemeenschappen. Maar tot het maken van een eenvoudige documentatie met behulp van een eenvoudig tekstbestand README.md (of .txt) u kunt uw beste of goede praktijken, tips of nuttige handleiding om derden de meest volledige en gedetailleerde informatie te geven die nodig is over wat er is gemaakt.

Voor ons artikel hebben we de Goede praktijken bedacht en bekendgemaakt door de "Code voor ontwikkelingsinitiatief" del Interamerican Development Bank, wat ons op een samengevatte manier vertelt dat goede documentatie op basis van een tekstbestand README.md (of .txt) Het moet als volgt worden gestructureerd:

Aanbevolen README-bestandsstructuur

• Beschrijving en context: Paragraaf waar de functionaliteiten moeten worden beschreven, de context waarin het is ontwikkeld en de ontwikkelproblemen die het hielp oplossen.
• Handleiding: Sectie waar instructies voor de eindgebruiker over het gebruik van de digitale tool moeten worden vermeld.
• Installatie gids: Sectie waar de installatie-instructies voor hergebruik en configuratie van de digitale tool moeten worden vermeld. Deze sectie is bedoeld voor ontwikkelaars.
• auteurs Sectie waar credits moeten worden gegeven aan de medewerkers van de tool.
• Licentie voor de toolcode: Sectie waarin de toestemmingen die aan derden worden verleend om de digitale tool opnieuw te gebruiken, moeten worden gespecificeerd.
• Licentie voor de documentatie van de tool: Sectie waar het type licentie vermeld in de gecreëerde documentatie moet worden vermeld.

In deze goede praktijken, raden ze ook aan om toe te voegen aan de README-bestand documentatie om het completer te maken, de volgende secties:

• Hoe u kunt bijdragen: Sectie die aan nieuwe ontwikkelaars het proces uitlegt om bij te dragen aan projecten.
• Gedragscode: Een deel dat de gedragscode uitlegt, legt de sociale normen, regels en verantwoordelijkheden vast die individuen en organisaties moeten volgen wanneer ze op enigerlei wijze omgaan met de digitale tool of hun gemeenschap.
• Badges: Sectie met de badges (kleine afbeeldingen ingebed in de README.md) die op een leesbare en beknopte manier de staat van de tool specificeren.
• Versie: Sectie met een lijst van de versies van de digitale tool en de functionaliteiten die aan elke versie zijn toegevoegd.
• Erkenningen: Sectie met de erkenningen aan andere mensen of organisaties die op de een of andere manier aan het project hebben bijgedragen.

Om deze informatie uit te breiden, op de Goede praktijken in zaken van documentatie voor de ontwikkeling van gratis software, Door de "Code voor ontwikkelingsinitiatief" del Interamerican Development Bank u kunt op de volgende link klikken: Documentatie - Gids voor het publiceren van digitale tools. En in andere publicaties zullen we het gedeelte waarnaar wordt verwezen onderzoeken goede praktijken op evaluatie en vergunningverlening del Gratis en open software zich.

Conclusie

We hopen dat esta "handige kleine post" op «Buenas prácticas» op het gebied van «documentación» te creëren bij het ontwikkelen «Software libre y abierto», van groot belang en nuttig zijn voor het geheel «Comunidad de Software Libre y Código Abierto» en een grote bijdrage aan de verspreiding van het prachtige, gigantische en groeiende ecosysteem van toepassingen van en voor «GNU/Linux».

En voor meer informatie, aarzel dan niet om er een te bezoeken Online bibliotheek als OpenLibra y jedit om te lezen boeken (pdf's) over dit onderwerp of anderen kennisgebieden. Voor nu, als je dit leuk vond «publicación», stop niet met het delen met anderen, in jouw Favoriete websites, kanalen, groepen of gemeenschappen van sociale netwerken, bij voorkeur gratis en open als Mastodont, of veilig en privé zoals Telegram.

Of bezoek gewoon onze homepage op DesdeLinux of word lid van het officiële kanaal Telegram van DesdeLinux om deze of andere interessante publicaties op te lezen en erop te stemmen «Software Libre», «Código Abierto», «GNU/Linux» en andere onderwerpen die verband houden met «Informática y la Computación», En de «Actualidad tecnológica».