Praktikat e mira për të zhvilluar një softuer të lirë dhe të hapur: Dokumentacioni

La dokumentim është dhe duhet të jetë një pjesë themelore e proces krijues dhe planifikim e të gjithë veprimtarisë njerëzore, dhe më shumë në fushën teknologjike, veçanërisht në fushën e Zhvillimi i softverit.

El qëllimi i të gjithë dokumentacionit duhet të jetë Ai mësoni palët e treta (përdoruesit, administratorët, mirëmbajtësit ose zhvilluesit e tjerë), të cilët zakonisht nuk janë të njohur me produkti (kodi, aplikacioni ose sistemi), si krijohet struktura e saj, funksionimi i saj dhe madje edhe nëse është e mundur, arsyeja për krijimin e saj dhe mënyra e saj e projektimit dhe funksionimit.

Për më tepër, në rastin specifik të Dokumentacioni i Programit të Lirë është jetik, pasi lejon garantimin e plotë të transferimi dhe fuqizimi i njohurive e nevojshme për përmbushjen e kënaqshme të 4 liritë promovuar nga ajo, të cilat janë:

• 0: Liria për të ekzekutuar programin si të doni, për çfarëdo qëllimi.
• 1: Liria për të hyrë dhe studiuar një program, dhe për ta ndryshuar ose përshtatur atë për përfitimin tuaj.
• 2: Liria për të ndarë ose rishpërndarë kopjet për të përhapur të njëjtën gjë dhe / ose për të ndihmuar të tjerët.
• 3: Liria për të shpërndarë kopjet e versioneve tuaja të modifikuara te palët e treta.

Një dokumentacion i mirë bën të mundur që produkti i krijuar:

• Përdoret në mënyrë korrekte dhe mësohet dhe mësohet më lehtë.
• Të kuptohet plotësisht nga ata që dëshirojnë ta modifikojnë për ta përmirësuar ose përshtatur.
• Jini të ndarë dhe të pritur me më shumë besim, midis të gjithë të njohurve dhe të huajve të mundshëm.
• Keni një masë më të mirë në mesin e publikut.

Praktikat e mira: Dokumentacioni

Bazat

Në rastin e Zhvillimi i Softuerit të Lirë dhe Burimit të Hapur, në përgjithësi, përdoruesit kryesorë të dokumentacionit në lidhje me modelin e produktit, janë ato që janë ose do të jenë, përgjegjës për mirëmbajtjen të së njëjtës. Dhe pa dokumentacion të mirë ose pa, e vetmja alternativë e zbatueshme është ta eksplorosh drejtpërdrejt atë, për ta arritur kuptojnë modelin dhe funksionin e tij.

Mos krijimi i dokumentacionit të mirë kur bëhet fjalë zhvilloni Softuer të Lirë, Burim të Hapur ose çfarëdo lloji tjetër të softuerit, duhet t'u dërgohet marrësve të tij të mundshëm (përdoruesit, administratorët, mirëmbajtësit ose zhvilluesit e tjerë) për të gjetur një mënyrë përmes një xhungle pa një hartë ose një busull.

Krijoni dokumentacion të mirë për secilin Program i Lirë, Burim i Hapur është gjithashtu e dobishme, pasi që, megjithëse dokumentimi ka një kostoInvestimi, nëse bëhet si duhet, ia vlen. Sepse, bota e program është plot histori rreth kodet e trashëgimisë programe, aplikacione ose sisteme të vjetra ose aktuale, që vetëm pak njerëz guxojnë t'i prekin, sepse pothuajse askush nuk i kupton. Programuesit përqendrohen në krijimin e kodit dhe jo në dokumentimin e tij të saktë dhe të plotë. Dhe kjo duhet të rregullohet.

Praktikat e mira mbi dokumentacionin në skedarët e tekstit README

Në rastin e Program i Lirë dhe Burim i Hapur, dokumentacioni shpesh është i kufizuar në skedarë me tekst, kur krijohet nga individë ose grupe të vogla programuesish ose bashkësish. Por, derisa të krijoni një dokumentacion të thjeshtë duke përdorur një të thjeshtë skedari teksti README.md (ose .txt) ju mund të keni tuajat praktikat më të mira ose të mira, këshilla ose udhëzues i dobishëm i krijimit për t'i sjellë palëve të treta informacionin më të plotë dhe të detajuar të nevojshëm për atë që është krijuar.

Për artikullin tonë, ne kemi marrë Praktikat e mira konceptuar dhe zbuluar nga "Kodi për Iniciativën e Zhvillimit" del Bank Interamerican Zhvillim, e cila në përmbledhje na tregon se dokumentacioni i mirë i bazuar në a skedari teksti README.md (ose .txt) Duhet të strukturohet si më poshtë:

Struktura e rekomanduar e skedarit README

• Përshkrimi dhe konteksti: Seksioni ku duhet të përshkruhen funksionalitetet, konteksti ku është zhvilluar dhe problemet e zhvillimit që ndihmoi për të zgjidhur.
• Udhëzuesi i përdoruesit: Seksioni ku duhet të përmenden udhëzimet për përdoruesin përfundimtar se si të fillojë përdorimi i mjetit dixhital.
• Udhëzuesi i instalimit: Seksioni ku duhet të përmenden udhëzimet e instalimit për të ripërdorur dhe konfiguruar mjetin dixhital. Ky seksion është menduar për zhvilluesit.
• autorët Seksioni ku kreditë duhet t'u jepen bashkëpunëtorëve të mjetit.
• Licencë për kodin e mjetit: Seksioni ku duhet të specifikohen lejet e dhëna palëve të treta për të ripërdorur mjetin dixhital.
• Licencë për dokumentacionin e mjetit: Seksioni ku duhet të përmendet lloji i licencës që përmbahet në dokumentacionin e krijuar.

Në këto praktika të mira, ata gjithashtu rekomandojnë shtimin e README dokumentacionin e skedarit për ta bërë atë më të plotë, seksionet vijuese:

• Si të kontribuoni: Seksioni që u shpjegon zhvilluesve të rinj procesin për të kontribuar në projekte.
• Kodi i Sjelljes: Seksioni që shpjegon kodin e sjelljes përcakton normat shoqërore, rregullat dhe përgjegjësitë që individët dhe organizatat duhet të ndjekin kur bashkëveprojnë në ndonjë mënyrë me mjetin dixhital ose komunitetin e tyre.
• Shenjat: Seksioni që tregon shënjat (imazhe të vogla të ngulitura në README.md) që specifikojnë në një mënyrë të lexueshme dhe koncize gjendjen e mjetit.
• Version: Seksioni që tregon një listë të versioneve të mjetit dixhital dhe funksionalitetet e shtuara në secilin version.
• Mirënjohje: Seksioni që përmban mirënjohje për njerëz të tjerë ose organizata që kanë kontribuar në një farë mënyre në projekt.

Për të zgjeruar këtë informacion, në Praktikat e mira në çështjet e dokumentim për zhvillimin e Free Software, nga "Kodi për Iniciativën e Zhvillimit" del Bank Interamerican Zhvillim mund të klikoni në lidhjen vijuese: Dokumentacioni - Udhëzues për botimin e mjeteve dixhitale. Dhe në botime të tjera do të shqyrtojmë pjesën që i referohet praktika të mira në vlerësimi dhe licencimi del Softuer i Lirë dhe i Hapur vetveten.

Përfundim

Shpresojmë që esta "post i dobishëm i vogël" në «Buenas prácticas» ne fushen e «documentación» për të krijuar kur zhvillohen «Software libre y abierto», të jetë me interes dhe dobi të madhe, për të gjithë «Comunidad de Software Libre y Código Abierto» dhe me një kontribut të madh në përhapjen e ekosistemit të mrekullueshëm, gjigant dhe në rritje të aplikacioneve të dhe për «GNU/Linux».

Dhe për më shumë informacion, mos hezitoni gjithmonë të vizitoni ndonjë Biblioteka online si OpenLibra y jedit te lexosh libra (PDF) për këtë temë apo të tjera fushat e njohurive. Tani për tani, nëse ju pëlqeu kjo «publicación», mos ndalo ndarjen e saj me të tjerët, në tuajin Uebsajtet, kanalet, grupet ose komunitetet e preferuara të rrjeteve sociale, mundësisht falas dhe të hapura si Mastodont, ose si të sigurta dhe private Telegram.

Ose thjesht vizitoni faqen tonë në DesdeLinux ose bashkohuni në Kanalin zyrtar Telegrami i DesdeLinux për të lexuar dhe votuar për këtë ose botime të tjera interesante në «Software Libre», «Código Abierto», «GNU/Linux» dhe tema të tjera që lidhen me «Informática y la Computación», Dhe «Actualidad tecnológica».