Head tavad vaba ja avatud tarkvara väljatöötamiseks: dokumentatsioon

La dokumentatsioon on ja peaks olema loomeprotsess ja planeerimine kogu inimtegevusest ja rohkem tehnoloogia valdkonnas, eriti Tarkvaraarendus.

El kogu dokumentatsiooni eesmärk see peab olema Tema õpetada kolmandaid osapooli (kasutajaid, administraatoreid, hooldajaid või muid arendajaid), kes pole tavaliselt toode (kood, rakendus või süsteem), kuidas see on loodud selle struktuur, toimimine ja isegi kui võimalik, selle loomise põhjus ning kujundus- ja toimimisviis.

Lisaks sellele konkreetsel juhul Vaba tarkvara dokumentatsioon on ülioluline, kuna see võimaldab täielikult garanteerida teadmiste edasiandmine ja võimestamine mis on vajalikud programmi rahuldavaks täitmiseks 4 vabadust mis on:

• 0: Vabadus käitada programmi mis tahes eesmärgil.
• 1: Vabadus programmile juurde pääseda ja seda õppida ning seda enda huvides muuta või kohandada.
• 2: Koopiate jagamise või levitamise vabadus, et levitada sama ja / või aidata teisi.
• 3: Vabadus levitada oma muudetud versioonide koopiaid kolmandatele isikutele.

Hea dokumentatsioon võimaldab seetõttu loodud toodet:

• Seda kasutatakse õigesti ning seda on lihtsam õpetada ja õppida.
• Neile, kes soovivad seda muuta, et seda paremaks muuta või kohandada, tuleb neid põhjalikult mõista.
• Olge kõigi potentsiaalsete tuttavate ja võõraste inimeste seas jagatud ja vastu võetud enesekindlamalt.
• Olge parem mass avalikkuse hulgas.

Head tavad: dokumentatsioon

Põhialused

Puhul Vaba tarkvara ja avatud lähtekoodiga arendamine, üldiselt dokumentatsiooni peamised kasutajad tootedisaini suhtes on need, mis on või jäävad, vastutab hoolduse eest sama. Ja ilma hea või puuduva dokumentatsioonita on ainus toimiv alternatiiv selle otsene uurimine, saavutamine mõista selle ülesehitust ja funktsiooni.

Ei loo head dokumentatsiooni arendada vaba tarkvara, avatud lähtekoodiga või mis tahes muud tüüpi tarkvara, tuleb saata selle võimalikele adressaatidele (kasutajad, administraatorid, hooldajad või muud arendajad) leida tee läbi džungli ilma kaardi või kompassita.

Looge igaühele hea dokumentatsioon Vaba tarkvara, avatud lähtekoodiga see on ka kasulik, sest kuigi dokumenteerimine maksabInvesteering, kui see on õigesti tehtud, on seda väärt. Sest, maailma tarkvara on täis lugusid pärandkoodid vanad või praegused programmid, rakendused või süsteemid, mida ainult vähesed inimesed julgevad puudutada, sest peaaegu keegi ei saa sellest aru. Programmeerijad keskenduvad koodi loomisele ja selle õigele ja täielikule dokumenteerimisele. Ja see tuleb parandada.

README-failide dokumentatsiooni head tavad

Puhul Vaba tarkvara ja avatud lähtekoodiga, dokumentatsioon piirdub sageli tekstifailidega, kui selle loovad üksikisikud või väikesed programmeerijate rühmad või kogukonnad. Kuid kuni lihtsa dokumendi loomiseni tekstifail README.md (või .txt) saate oma parimad või head tavad, näpunäiteid või kasulikku loomisjuhendit, et tuua kolmandatele isikutele võimalikult täielikku ja üksikasjalikku teavet selle kohta, mis on loodu kohta vajalik.

Meie artikli jaoks oleme võtnud Hea tava kavandatud ja avalikustatud "Arengualgatuse koodeks" kohta Ameerika Arengupank, mis kokkuvõtlikult ütleb meile, et hea dokumentatsioon põhineb a tekstifail README.md (või .txt) See peab olema üles ehitatud järgmiselt:

Soovitatav faili struktuur README

• Kirjeldus ja kontekst: Jaotis, kus tuleb kirjeldada funktsionaalsusi, kontekst, kus see välja töötati, ja arenguprobleemid, mida see aitas lahendada.
• Kasutusjuhend: Jaotis, kus tuleks mainida juhiseid lõpptarbijale, kuidas digitaalset tööriista kasutama hakata.
• Paigaldusjuhend: Jaotis, kus tuleks mainida digitaalse tööriista korduskasutamise ja konfigureerimise paigaldusjuhiseid. See jaotis on mõeldud arendajatele.
• autorid Jaotis, kus tööriista kaasautoritele tuleb anda krediiti.
• Tööriistakoodi litsents: Jaotis, kus tuleb täpsustada kolmandatele isikutele antud õigused digitaalse tööriista taaskasutamiseks.
• Tööriista dokumentatsiooni litsents: Jaotis, kus tuleb mainida loodud dokumentatsioonis sisalduvat litsentsi tüüpi.

nende head tavad, soovitavad nad ka README faili dokumentatsioon selle täielikumaks muutmiseks järgige järgmisi jaotisi:

• Kuidas panustada: Jaotis, mis selgitab uutele arendajatele projektidesse panustamise protsessi.
• Käitumisjuhend: Käitumisjuhendit selgitavas osas kehtestatakse sotsiaalsed normid, reeglid ja kohustused, mida üksikisikud ja organisatsioonid peavad järgima digitaalse tööriista või nende kogukonnaga mis tahes viisil suheldes.
• Märgid: Jaotis, mis näitab märke (README.md-sse kinnitatud väikseid pilte), mis määravad loetaval ja kokkuvõtlikult tööriista oleku.
• Versioon: Jaotis, mis näitab digitaalse tööriista versioonide loendit ja igale versioonile lisatud funktsioone.
• Tänusõnad: Jaotis, mis sisaldab tunnustust teistele inimestele või organisatsioonidele, kes on projekti mingil moel kaasa aidanud.

Selle teabe laiendamiseks avage veebileht Hea tava küsimustes dokumentatsioon arendamiseks Vaba tarkvara, poolt "Arengualgatuse koodeks" kohta Ameerika Arengupank võite klõpsata järgmisel lingil: Dokumentatsioon - juhend digitaalsete tööriistade avaldamiseks. Ja teistes väljaannetes uurime viidatavat osa head tavad umbes hindamine ja litsentsimine kohta Vaba ja avatud tarkvara ise.

Järeldus

Loodame seda see "kasulik väike postitus" umbes «Buenas prácticas» valdkonnas «documentación» arendamisel luua «Software libre y abierto», pakub tervikuna suurt huvi ja kasulikkust «Comunidad de Software Libre y Código Abierto» ja suur panus imelise, hiiglasliku ja kasvava ökosüsteemi levitamisse ja heaks «GNU/Linux».

Ja lisateabe saamiseks külastage alati mõnda neist Veebiraamatukogu kui OpenLibra y jedit lugema raamatud (PDF-id) sellel teemal või teistel teadmiste valdkonnad. Praegu, kui see teile meeldis «publicación», ära lõpeta selle jagamist teistega, teie Lemmikveebisaidid, kanalid, rühmad või kogukonnad sotsiaalvõrgustikke, eelistatavalt tasuta ja avatud Paksunahalinevõi turvaline ja privaatne Telegramm.

Või lihtsalt külastage meie kodulehte aadressil DesdeLinux või liituge ametliku kanaliga Telegramm DesdeLinux selle või muude huvitavate väljaannete kohta lugemiseks ja nende poolt hääletamiseks «Software Libre», «Código Abierto», «GNU/Linux» ja muud teemad, mis on seotud «Informática y la Computación»Ja «Actualidad tecnológica».