God praksis til udvikling af gratis og åben software: Dokumentation

La dokumentation er og bør være en grundlæggende del af kreativ proces og planlægning af al menneskelig aktivitet og mere inden for det teknologiske område, især inden for området Softwareudvikling.

El formålet med al dokumentation det må være ham undervise tredjeparter (brugere, administratorer, vedligeholdere eller andre udviklere), som normalt ikke er fortrolige med produkt (kode, applikation eller system), hvordan er det skabt dens struktur, dens drift og selv om det er muligt, årsagen til dets oprettelse og dets måde at designe og betjene på.

I det specifikke tilfælde af Gratis software-dokumentation er afgørende, da det giver mulighed for fuldt ud at garantere videnoverførsel og empowerment nødvendigt for en tilfredsstillende opfyldelse af 4 friheder fremmes af det, som er:

• 0: Friheden til at køre programmet, uanset hvad du vil, til ethvert formål.
• 1: Friheden til at få adgang til og studere et program og ændre eller tilpasse det til din egen fordel.
• 2: Friheden til at dele eller omfordele kopier for at sprede det samme og / eller hjælpe andre.
• 3: Friheden til at distribuere kopier af dine modificerede versioner til tredjeparter.

En god dokumentation gør det derfor muligt, at det oprettede produkt:

• Det bruges korrekt, og det læres lettere og læres lettere.
• Bliv grundigt forstået af dem, der ønsker at ændre det for at forbedre eller tilpasse det.
• Bliv delt og modtaget med mere selvtillid blandt alle potentielle bekendte og fremmede.
• Få en bedre masse blandt offentligheden.

God praksis: Dokumentation

Grundlæggende

I tilfælde af Udvikling af fri software og open source, generelt, hovedbrugerne af dokumentationen relateret til produktdesign, er dem, der er eller vil være, ansvarlig for vedligeholdelse af det samme. Og uden god eller ingen dokumentation er det eneste levedygtige alternativ at udforske det direkte og opnå det forstå dets design og funktion.

Skaber ikke god dokumentation, når det kommer til udvikle fri software, open source eller enhver anden type software skal sendes til dets mulige modtagere (brugere, administratorer, vedligeholdere eller andre udviklere) at finde en vej gennem en jungle uden kort eller kompas.

Opret god dokumentation til hver Gratis software, Open Source det er også gavnligt, selvom dokumentation har en prisInvesteringen, hvis den gøres korrekt, er det værd. Fordi, verden af Software er fuld af historier om ældre koder gamle eller aktuelle programmer, applikationer eller systemer, som kun få mennesker tør røre ved, fordi næsten ingen forstår. Programmører fokuserer på at oprette kode og ikke dokumentere den korrekt og fuldstændigt. Og dette skal afhjælpes.

God praksis for dokumentation i README tekstfiler

I tilfælde af Gratis software og open sourceer dokumentation ofte begrænset til tekstfiler, når den oprettes af enkeltpersoner eller små grupper af programmører eller samfund. Men indtil du opretter en simpel dokumentation ved hjælp af en simpel tekstfil README.md (eller .txt) du kan få din bedste eller gode fremgangsmåder, tip eller nyttig vejledning til oprettelse for at bringe tredjeparter den mest komplette og detaljerede information, der er nødvendig om, hvad der er oprettet.

For vores artikel har vi taget God praksis undfanget og afsløret af "Kode for udviklingsinitiativ" den Interamerikanske Udviklingsbank, som i resumé fortæller os, at god dokumentation baseret på en tekstfil README.md (eller .txt) Den skal være struktureret som følger:

Anbefalet README filstruktur

• Beskrivelse og sammenhæng: Afsnit, hvor du skal beskrive funktionaliteterne, den kontekst, hvor den blev udviklet, og de udviklingsproblemer, den hjalp med at løse.
• Bruger manual: Afsnit, hvor instruktioner til slutbrugeren om, hvordan man begynder at bruge det digitale værktøj, bør nævnes.
• Installationsvejledning: Afsnittet, hvor installationsinstruktionerne til genbrug og konfiguration af det digitale værktøj skal nævnes. Dette afsnit er beregnet til udviklere.
• forfattere Afsnit, hvor der skal gives kreditter til værktøjets samarbejdspartnere.
• Licens til værktøjskoden: Det afsnit, hvor tilladelserne til tredjemand til at genbruge det digitale værktøj skal specificeres.
• Licens til dokumentation af værktøjet: Afsnit, hvor licenstypen i den oprettede dokumentation skal nævnes.

I disse god praksis, de anbefaler også at tilføje til README-fildokumentation for at gøre det mere komplet, følgende afsnit:

• Sådan bidrager du: Afsnit, der forklarer nye udviklere processen med at bidrage til projekter.
• Adfærdskodeks: Afsnit, der forklarer adfærdskodeksen, fastlægger de sociale normer, regler og ansvar, som enkeltpersoner og organisationer skal følge, når de på nogen måde interagerer med det digitale værktøj eller deres samfund.
• Badges: Afsnit, der viser badges (små billeder integreret i README.md), der på en læsbar og kortfattet måde angiver værktøjets tilstand.
• Version: Afsnit, der angiver en liste over versionerne af det digitale værktøj og de funktioner, der er tilføjet til hver version.
• Anerkendelser: Afsnit, der indeholder anerkendelser til andre mennesker eller organisationer, der på en eller anden måde har bidraget til projektet.

For at udvide disse oplysninger på God praksis i sager om dokumentation til udvikling af Free Software, ved "Kode for udviklingsinitiativ" den Interamerikanske Udviklingsbank du kan klikke på følgende link: Dokumentation - Vejledning til udgivelse af digitale værktøjer. Og i andre publikationer vil vi undersøge den del, der henviser til god praksis på evaluering og licensering den Gratis og åben software dem selv.

Konklusion

Det håber vi dette "nyttigt lille indlæg" på «Buenas prácticas» inden for «documentación» at skabe, når man udvikler «Software libre y abierto», være af stor interesse og nytte for hele det «Comunidad de Software Libre y Código Abierto» og med stort bidrag til spredningen af ​​det vidunderlige, gigantiske og voksende økosystem af applikationer af og til «GNU/Linux».

Og for mere information, tøv ikke altid med at besøge nogen Online bibliotek som OpenLibra y jedit at læse bøger (PDF-filer) om dette emne eller andre videnområder. For nu, hvis du kunne lide dette «publicación», stop ikke med at dele det med andre, i din Favoritwebsteder, kanaler, grupper eller samfund af sociale netværk, helst gratis og åbent som Mastodon, eller sikker og privat lignende Telegram.

Eller besøg blot vores hjemmeside på DesdeLinux eller tilmeld dig den officielle kanal Telegram af DesdeLinux at læse og stemme på denne eller andre interessante publikationer om «Software Libre», «Código Abierto», «GNU/Linux» og andre emner relateret til «Informática y la Computación»Og «Actualidad tecnológica».