Dobre prakse za razvoj besplatnog i otvorenog softvera: dokumentacija

La documentación jest i trebao bi biti temeljni dio kreativni proces i planiranje svih ljudskih aktivnosti, a više na tehnološkom polju, posebno na području Razvoj softvera.

El svrha sve dokumentacije to mora biti On podučavati treće strane (korisnike, administratore, održavatelje ili druge programere), koji obično nisu upoznati s proizvod (kod, aplikacija ili sustav), kako je stvoren njegova struktura, njegovo djelovanje pa čak i ako je to moguće, razlog nastanka i način dizajniranja i rada.

Nadalje, u konkretnom slučaju Dokumentacija o besplatnom softveru je od vitalnog značaja, jer omogućuje potpuno jamstvo prijenos znanja i osnaživanje potrebno za zadovoljavajuće ispunjenje 4 slobode koje promovira, a to su:

• 0: Sloboda pokretanja programa kako god želite u bilo koju svrhu.
• 1: Sloboda pristupa i proučavanja programa te njegova promjena ili prilagodba u vašu vlastitu korist.
• 2: Sloboda dijeljenja ili ponovne distribucije kopija radi širenja istih i / ili pomoći drugima.
• 3: Sloboda distribucije kopija vaših izmijenjenih verzija trećim stranama.

Dobra dokumentacija omogućava, dakle, da stvoreni proizvod:

• Koristi se ispravno, a lakše se podučava i uči.
• Oni koji ga žele izmijeniti kako bi ga poboljšali ili prilagodili neka vas temeljito razumiju.
• Budite podijeljeni i primljeni s više samopouzdanja, među svim potencijalnim poznanicima i strancima.
• Imati bolju misu u javnosti.

Dobre prakse: Dokumentacija

Fundamentos

U slučaju Razvoj slobodnog softvera i otvorenog koda, općenito, glavni korisnici dokumentacije u odnosu na dizajn proizvoda, jesu li oni koji jesu ili će biti, odgovoran za održavanje istog. I bez dobre ili bez dokumentacije, jedina održiva alternativa je izravno je istražiti, postići razumjeti njegov dizajn i funkciju.

Ne stvaranje dobre dokumentacije kada je riječ o razviti slobodni softver, otvoreni izvor ili bilo koju drugu vrstu softvera, jest slanje mogućim primateljima (korisnici, administratori, održavatelji ili drugi programeri) pronaći put kroz džunglu bez karte ili kompasa.

Stvorite dobru dokumentaciju za svaku Slobodni softver, otvoreni izvor to je također korisno jer, iako dokumentiranje ima trošakAko se investicija pravilno izvede, isplati se. Jer, svijet softver je pun priča o naslijeđeni kodovi stari ili trenutni programi, aplikacije ili sustavi, kojih se samo malo ljudi usuđuje dotaknuti, jer gotovo nitko ne razumije. Programeri se usredotočuju na stvaranje koda, a ne na njegovo ispravno i potpuno dokumentiranje. I to se mora popraviti.

Dobre prakse u vezi s dokumentacijom u tekstualnim datotekama README

U slučaju Slobodni softver i otvoreni kod, dokumentacija je često ograničena na tekstualne datoteke, kada je kreiraju pojedinci ili male skupine programera ili zajednice. Ali, do stvaranja jednostavne dokumentacije pomoću jednostavne tekstualna datoteka README.md (ili .txt) možeš dobiti svoj najbolje ili dobre prakse, savjete ili korisne upute za stvaranje kako biste trećim stranama pružili najcjelovitije i najdetaljnije informacije potrebne o stvorenom.

Za naš smo članak uzeli Dobre prakse osmislio i otkrio "Kodeks za razvojnu inicijativu" del Interamerican banka za razvoj, što ukratko govori da dobra dokumentacija temeljena na a tekstualna datoteka README.md (ili .txt) Mora biti strukturiran na sljedeći način:

Preporučena struktura datoteke README

• Opis i kontekst: Odjeljak u kojem morate opisati funkcionalnosti, kontekst u kojem su razvijene i razvojne probleme koje je pomogao riješiti.
• Korisnički priručnik: Odjeljak u kojem se trebaju spomenuti upute krajnjem korisniku o tome kako početi koristiti digitalni alat.
• Vodič za instalaciju: Odjeljak u kojem treba spomenuti instalacijske upute za ponovnu upotrebu i konfiguriranje digitalnog alata. Ovaj je odjeljak namijenjen programerima.
• autori Odjeljak u kojem se zasluge moraju dodijeliti suradnicima alata.
• Licenca za kod alata: Odjeljak u kojem moraju biti navedena dopuštenja trećim stranama za ponovnu upotrebu digitalnog alata.
• Licenca za dokumentaciju alata: Odjeljak u kojem se mora navesti vrsta licence sadržana u kreiranoj dokumentaciji.

U ovim dobra praksa, oni također preporučuju dodavanje u README dokumentacija datoteke da bi bio potpuniji, sljedeći odjeljci:

• Kako doprinijeti: Odjeljak koji novim programerima objašnjava postupak doprinosa projektima.
• Kodeks ponašanja: Odjeljak koji objašnjava kodeks ponašanja utvrđuje društvene norme, pravila i odgovornosti koje pojedinci i organizacije moraju slijediti kada na bilo koji način komuniciraju s digitalnim alatom ili njihovom zajednicom.
• Značke: Odjeljak koji prikazuje značke (male slike ugrađene u README.md) koje na čitljiv i sažet način određuju stanje alata.
• Verzija: Odjeljak koji ukazuje na popis verzija digitalnog alata i funkcionalnosti dodanih svakoj verziji.
• Zahvalnice: Odjeljak koji sadrži priznanja drugim ljudima ili organizacijama koje su na neki način dale svoj doprinos projektu.

Da biste proširili ove podatke, na Dobre prakse u pitanjima dokumentacija za razvoj Slobodni softver, od strane "Kodeks za razvojnu inicijativu" del Interamerican banka za razvoj možete kliknuti na sljedeću poveznicu: Dokumentacija - Vodič za objavljivanje digitalnih alata. A u drugim ćemo publikacijama istražiti dio koji se odnosi na dobra praksa o ocjenjivanje i licenciranje del Besplatni i otvoreni softver se.

Zaključak

Nadamo se da esta "koristan mali post" na «Buenas prácticas» u polju «documentación» stvoriti prilikom razvoja «Software libre y abierto», od velikog je interesa i korisnosti za cijelu «Comunidad de Software Libre y Código Abierto» i velikog doprinosa širenju divnog, gigantskog i rastućeg ekosustava aplikacija i za «GNU/Linux».

A za više informacija, nemojte uvijek oklijevati posjetiti bilo koju Internetska knjižnica kao OpenLibra y jedit čitati knjige (PDF-ovi) na ovu temu ili druge područja znanja. Za sada, ako vam se ovo svidjelo «publicación», nemojte ga prestati dijeliti s drugima, u vašem Omiljene web stranice, kanali, grupe ili zajednice društvenih mreža, po mogućnosti besplatnih i otvorenih kao Mastodont, ili sigurno i privatno poput Telegram.

Ili jednostavno posjetite našu početnu stranicu na DesdeLinux ili se pridružite službenom kanalu Telegram od DesdeLinux čitati i glasati za ovu ili druge zanimljive publikacije na «Software Libre», «Código Abierto», «GNU/Linux» i druge teme povezane s «Informática y la Computación», I «Actualidad tecnológica».