Geroji nemokamos ir atviros programinės įrangos kūrimo praktika: dokumentacija

La Dokumentacija yra ir turėtų būti pagrindinė programos dalis kūrybinis procesas ir planavimas visos žmogaus veiklos ir dar daugiau technologinėje srityje, ypač Programinės įrangos kūrimas.

El visų dokumentų paskirtis tai turi būti Jis mokyti trečiąsias šalis (vartotojus, administratorius, prižiūrėtojus ar kitus kūrėjus), kurie paprastai nėra susipažinę su produktas (kodas, programa ar sistema), kaip jis sukurtas jo struktūra, veikimas ir net jei įmanoma, jo sukūrimo priežastis bei projektavimo ir veikimo būdas.

Be to, konkrečiu atveju Nemokama programinės įrangos dokumentacija yra gyvybiškai svarbi, nes tai leidžia visiškai garantuoti žinių perdavimas ir įgalinimas būtinas patenkinamai įgyvendinti 4 laisvės kurie yra:

• 0: Laisvė vykdyti programą taip, kaip norite, bet kokiems tikslams.
• 1: Laisvė susipažinti su programa ir ją studijuoti, ją pakeisti ar pritaikyti savo naudai.
• 2: Laisvė dalytis ar platinti kopijas, kad skleistų tą patį ir (arba) padėtų kitiems.
• 3: Laisvė platinti modifikuotų versijų kopijas trečiosioms šalims.

Dėl geros dokumentacijos sukurtas produktas leidžia:

• Jis naudojamas teisingai, jo lengviau išmokti ir išmokti.
• Būkite gerai suprantami tiems, kurie nori jį modifikuoti, kad patobulintų ar pritaikytų.
• Būkite dalijamasi ir priimamas su pasitikėjimu tarp visų potencialių pažįstamų ir nepažįstamų žmonių.
• Turėkite geresnę masę tarp visuomenės.

Geroji patirtis: dokumentacija

Pagrindai

Tuo atveju, kai Laisvos programinės įrangos ir atvirojo kodo kūrimas, paprastai, pagrindiniai dokumentacijos vartotojai palyginti su produkto dizainu, yra tie, kurie yra ar bus, atsakingas už priežiūrą to paties. Ir neturint gerų dokumentų ar neturint jų, vienintelė perspektyvi alternatyva yra tiesiogiai juos ištirti, pasiekti suprasti jo dizainą ir funkciją.

Nesukurkite geros dokumentacijos kurti nemokamą programinę įrangą, atvirąjį kodą ar bet kokio kito tipo programinė įranga turi būti siunčiama jos galimiems gavėjams (vartotojai, administratoriai, prižiūrėtojai ar kiti kūrėjai) rasti kelią per džiungles be žemėlapio ar kompaso.

Kiekvienam sukurkite gerą dokumentaciją Nemokama programinė įranga, atvirasis šaltinis tai taip pat naudinga, nes, nors dokumentavimas turi išlaidųInvesticija, jei ji atlikta teisingai, yra verta. Nes, pasaulis programinė įranga yra pilna istorijų apie senieji kodai senos ar esamos programos, programos ar sistemos, prie kurių tik nedaugelis žmonių ryžtasi prisiliesti, nes beveik niekas nesupranta. Programuotojai daugiausia dėmesio skiria kodo kūrimui, o ne jo dokumentavimui teisingai ir visiškai. Ir tai turi būti ištaisyta.

Geroji dokumentavimo README teksto rinkmenose praktika

Tuo atveju, kai Nemokama programinė įranga ir atvirasis šaltinis, dokumentai dažnai apsiriboja tekstiniais failais, kai juos kuria asmenys ar nedidelės programuotojų grupės ar bendruomenės. Bet kol nebus sukurta paprasta dokumentacija naudojant paprastą tekstinis failas README.md (arba .txt) tu gali turėti savo geriausia ar geriausia praktika, patarimų ar naudingo kūrinio vadovo, kad trečiosioms šalims pateiktų kuo išsamesnę ir išsamesnę informaciją apie sukurtą.

Mūsų straipsniui mes paėmėme Geroji patirtis sugalvota ir atskleista "Vystymosi iniciatyvos kodas" del Interamerican plėtros bankas, kuris apibendrinant mums sako, kad gera dokumentacija, pagrįsta a tekstinis failas README.md (arba .txt) Jo struktūra turi būti tokia:

Rekomenduojama README failo struktūra

• Aprašymas ir kontekstas: Skyrius, kuriame turi būti aprašytos funkcijos, kontekstas, kuriame jis buvo sukurtas, ir plėtros problemos, kurias jis padėjo išspręsti.
• Vartotojo vadovas: Skyrius, kuriame turėtų būti paminėtos instrukcijos galutiniam vartotojui, kaip pradėti naudoti skaitmeninį įrankį.
• Diegimo vadovas: Skyrius, kuriame reikėtų paminėti diegimo instrukcijas, kaip pakartotinai naudoti ir konfigūruoti skaitmeninį įrankį. Šis skyrius skirtas kūrėjams.
• autoriai Skyrius, kuriame turi būti suteikiami kreditai įrankio bendradarbiams.
• Įrankio kodo licencija: Skyrius, kuriame turi būti nurodyti trečiosioms šalims suteikti leidimai pakartotinai naudoti skaitmeninį įrankį.
• Įrankio dokumentacijos licencija: Skyrius, kuriame turi būti paminėta sukurtos dokumentacijos licencijos rūšis.

Šiuose gerą praktiką, jie taip pat rekomenduoja pridėti „README“ bylos dokumentacija kad jis būtų išsamesnis, skyriai:

• Kaip prisidėti: Skyrius, kuriame naujiems kūrėjams paaiškinamas indėlis į projektus.
• Elgesio kodeksas: Skyriuje, kuriame paaiškinamas elgesio kodeksas, nustatomos socialinės normos, taisyklės ir atsakomybė, kurių asmenys ir organizacijos privalo laikytis, bet kokiu būdu bendraudami su skaitmeniniu įrankiu ar savo bendruomene.
• Ženkleliai: Skyrius, kuriame rodomi ženkleliai (maži vaizdai, įterpti į README.md), kurie suprantamai ir glaustai nurodo įrankio būseną.
• Versija: Skyrius, kuriame nurodomas skaitmeninio įrankio versijų sąrašas ir kiekvienai versijai pridedamos funkcijos.
• Padėkos: Skyrius, kuriame pateikiami padėkos kitiems žmonėms ar organizacijoms, kurie kažkokiu būdu prisidėjo prie projekto.

Norėdami išplėsti šią informaciją, apsilankykite Geroji patirtis klausimais dokumentacija plėtrai Nemokama programinė įranga, prie "Vystymosi iniciatyvos kodas" del Interamerican plėtros bankas galite spustelėti šią nuorodą: Dokumentacija - skaitmeninių įrankių publikavimo vadovas. Kituose leidiniuose nagrinėsime dalį, į kurią kalbama gerą praktiką apie vertinimas ir licencijavimas del Nemokama ir atvira programinė įranga patys.

Išvada

Mes to tikimės tai "naudingas mažas įrašas" apie «Buenas prácticas» srityje «documentación» kurti kuriant «Software libre y abierto», yra labai įdomus ir naudingas visam «Comunidad de Software Libre y Código Abierto» ir labai prisideda prie nuostabios, gigantiškos ir augančios ekosistemos sklaidos «GNU/Linux».

Norėdami gauti daugiau informacijos, visada nedvejodami apsilankykite bet kuriame Internetinė biblioteka kaip „OpenLibra“ y jeditas Skaityti knygos (PDF) šia ar kitomis temomis žinių srityse. Kol kas, jei jums tai patiko «publicación», nenustok juo dalintis su kitais, jūsų Mėgstamos svetainės, kanalai, grupės ar bendruomenės socialinių tinklų, pageidautina nemokamų ir atvirų kaip Mastadonasarba saugus ir privatus Telegram.

Arba tiesiog apsilankykite mūsų pagrindiniame puslapyje DesdeLinux arba prisijungti prie oficialaus kanalo Telegrama iš DesdeLinux skaityti ir balsuoti už šį ar kitus įdomius leidinius «Software Libre», «Código Abierto», «GNU/Linux» ir kitomis temomis, susijusiomis su «Informática y la Computación»Ir «Actualidad tecnológica».