God praxis för att utveckla fri och öppen programvara: dokumentation

La dokumentation är och bör vara en grundläggande del av kreativ process och planering av all mänsklig verksamhet och mer inom det tekniska området, särskilt inom området Mjukvaruutveckling.

El syftet med all dokumentation det måste vara honom lära ut tredje parter (användare, administratörer, underhållare eller andra utvecklare), som vanligtvis inte känner till produkt (kod, applikation eller system), hur skapas det dess struktur, dess funktion och även om möjligt, orsaken till dess skapande och dess sätt att utforma och använda.

I det specifika fallet med Dokumentation om fri programvara är viktig, eftersom det gör det möjligt att helt garantera kunskapsöverföring och bemyndigande nödvändigt för att tillfredsställande uppfyllelse av 4 friheter främjas av det, vilka är:

• 0: Friheten att köra programmet som önskat, för alla syften.
• 1: Friheten att komma åt och studera ett program och ändra eller anpassa det till din egen fördel.
• 2: Friheten att dela eller omfördela kopior för att sprida samma och / eller hjälpa andra.
• 3: Friheten att distribuera kopior av dina modifierade versioner till tredje part.

En bra dokumentation gör det därför möjligt att den skapade produkten:

• Det används korrekt och det lärs lättare och lärs lättare.
• Förstås grundligt av dem som vill ändra det för att förbättra eller anpassa det.
• Bli delad och mottagen med mer självförtroende bland alla potentiella bekanta och främlingar.
• Ha en bättre massa bland allmänheten.

God praxis: Dokumentation

Grundläggande

I fallet med Utveckling av fri programvara och öppen källkod, rent generellt, huvudsakliga användare av dokumentationen i förhållande till produktdesign, är de som är eller kommer att vara, ansvarig för underhåll av samma. Och utan god eller ingen dokumentation är det enda gångbara alternativet att direkt utforska det, att uppnå förstå dess design och funktion.

Skapar inte bra dokumentation när det gäller utveckla fri programvara, öppen källkod eller någon annan typ av programvara, ska sändas till dess möjliga mottagare (användare, administratörer, underhållare eller andra utvecklare) för att hitta en väg genom en djungel utan karta eller kompass.

Skapa bra dokumentation för varje Fri programvara, öppen källkod det är också fördelaktigt, även om att dokumentera kostarInvesteringen, om den görs korrekt, är värt det. För, världen av Mjukvara är full av berättelser om äldre koder gamla eller aktuella program, applikationer eller system, som bara få människor vågar röra, för nästan ingen förstår. Programmerare fokuserar på att skapa kod och inte dokumentera den korrekt och fullständigt. Och detta måste åtgärdas.

God praxis för dokumentation i README-textfiler

I fallet med Fri programvara och öppen källkodär dokumentation ofta begränsad till textfiler när den skapas av individer eller små grupper av programmerare eller samhällen. Men tills du skapar en enkel dokumentation med en enkel textfil README.md (eller .txt) du kan få din bästa eller goda metoder, tips eller användbar guide för att skapa tredjeparter den mest kompletta och detaljerade information som behövs om skapandet.

För vår artikel har vi tagit Goda rutiner tänkt och avslöjas av "Kod för utvecklingsinitiativ" del Interamerikanska utvecklingsbanken, som sammanfattar oss att god dokumentation baserad på en textfil README.md (eller .txt) Den måste struktureras enligt följande:

Rekommenderad README-filstruktur

• Beskrivning och sammanhang: Avsnitt där funktionerna måste beskrivas, sammanhanget där det utvecklades och utvecklingsproblemen det hjälpte till att lösa.
• Användarmanual: Avsnitt där instruktioner till slutanvändaren om hur man börjar använda det digitala verktyget bör nämnas.
• Installationsguide: Avsnitt där installationsinstruktionerna för återanvändning och konfigurering av det digitala verktyget bör nämnas. Detta avsnitt är avsett för utvecklare.
• författarna Avsnitt där poäng måste ges till redaktörens medarbetare.
• Licens för verktygskoden: Avsnitt där behörigheter som ges till tredje part för att återanvända det digitala verktyget måste anges.
• Licens för dokumentation av verktyget: Avsnitt där typen av licens i den skapade dokumentationen måste anges.

I dessa god praxis, de rekommenderar också att lägga till README-fildokumentation För att göra det mer komplett, följande avsnitt:

• Hur man bidrar: Avsnitt som förklarar för nya utvecklare processen att bidra till projekt.
• Uppförandekod: Avsnitt som förklarar uppförandekoden fastställer de sociala normer, regler och ansvar som individer och organisationer måste följa när de på något sätt interagerar med det digitala verktyget eller deras samhälle.
• Märken: Avsnitt som visar märken (små bilder inbäddade i README.md) som på ett läsbart och koncist sätt anger verktygets tillstånd.
• Version: Avsnitt som visar en lista över versionerna av det digitala verktyget och de funktioner som läggs till i varje version.
• Tack: Avsnitt som innehåller bekräftelser till andra personer eller organisationer som på något sätt har bidragit till projektet.

För att utöka denna information, på Goda rutiner i frågor om dokumentation för utvecklingen av fri programvara, vid "Kod för utvecklingsinitiativ" del Interamerikanska utvecklingsbanken du kan klicka på följande länk: Dokumentation - Guide för publicering av digitala verktyg. Och i andra publikationer kommer vi att utforska den del som hänvisar till god praxis om utvärdering och licensiering del Gratis och öppen programvara sig själva.

Slutsats

Vi hoppas att detta "hjälpsamma lilla inlägg" på «Buenas prácticas» inom området för «documentación» att skapa när man utvecklar «Software libre y abierto», vara av stort intresse och nytta för hela tiden «Comunidad de Software Libre y Código Abierto» och med stort bidrag till spridningen av det underbara, gigantiska och växande ekosystemet för applikationer av och för «GNU/Linux».

Och för mer information, tveka inte att besöka någon Online-bibliotek som OpenLibra y jedit att läsa böcker (PDF-filer) om detta ämne eller andra kunskapsområden. För nu, om du gillade det här «publicación», sluta inte dela det med andra, i din Favoritwebbplatser, kanaler, grupper eller grupper av sociala nätverk, helst gratis och öppet som Mastodon, eller säker och privat liknande Telegram.

Eller helt enkelt besöka vår hemsida på DesdeLinux eller gå med i den officiella kanalen Telegram av DesdeLinux att läsa och rösta på denna eller andra intressanta publikationer på «Software Libre», «Código Abierto», «GNU/Linux» och andra ämnen relaterade till «Informática y la Computación», Och «Actualidad tecnológica».