Bune practici pentru dezvoltarea software-ului gratuit și deschis: documentație

La documentație este și ar trebui să fie o parte fundamentală a proces creativ și planificare a tuturor activităților umane și mai mult în domeniul tehnologic, în special în zona Dezvoltare de software.

El scopul tuturor documentelor trebuie să fie El învățați terți (utilizatori, administratori, mentenanți sau alți dezvoltatori), care nu sunt de obicei familiarizați cu produs (cod, aplicație sau sistem), cum este creat structura sa, funcționarea sa și chiar dacă este posibil, motivul creării sale și modul său de proiectare și operare.

Mai mult, în cazul specific al Documentarea software-ului gratuit este vitală, deoarece permite garantarea deplină a transferul de cunoștințe și împuternicire necesare pentru îndeplinirea satisfăcătoare a 4 libertăți promovate de acesta, care sunt:

• 0: Libertatea de a rula programul oricum doriți, în orice scop.
• 1: Libertatea de a accesa și studia un program și de a-l schimba sau adapta în beneficiul dvs.
• 2: Libertatea de a partaja sau redistribui copii pentru a le răspândi și / sau a ajuta pe ceilalți.
• 3: Libertatea de a distribui copii ale versiunilor dvs. modificate către terți.

O bună documentare face posibil, prin urmare, ca produsul creat:

• Este folosit corect și este mai ușor predat și învățat.
• Fiți bine înțeles de către cei care doresc să-l modifice pentru a-l îmbunătăți sau a-l adapta.
• Fii împărtășit și primit cu mai multă încredere, între toți potențialii cunoscuți și străini.
• Să ai o masă mai bună în rândul publicului.

Bune practici: documentare

Fundamentele

În cazul Dezvoltarea de software gratuit și open source, în general, principalii utilizatori ai documentației în raport cu designul produsului, sunt acelea care sunt sau vor fi, responsabil cu întreținerea de acelasi. Și fără documentație bună sau deloc, singura alternativă viabilă este explorarea directă, realizarea înțelegeți designul și funcția acestuia.

Nu creează o documentație bună atunci când vine vorba dezvolta software gratuit, open source sau orice alt tip de software, trebuie să fie trimis către eventualii săi destinatari (utilizatori, administratori, mentenanți sau alți dezvoltatori) pentru a găsi o cale printr-o junglă fără hartă sau busolă.

Creați o documentație bună pentru fiecare Software gratuit, Open Source este, de asemenea, benefic, deoarece, deși documentarea are un costInvestiția, dacă este făcută corect, merită. Pentru că, lumea Software este plin de povești despre coduri vechi programe, aplicații sau sisteme vechi sau actuale, pe care doar puțini oameni îndrăznesc să le atingă, deoarece aproape nimeni nu înțelege. Programatorii se concentrează pe crearea codului și nu pe documentarea corectă și completă a acestuia. Și acest lucru trebuie remediat.

Bune practici privind documentarea în fișierele text README

În cazul Software gratuit și Open Source, documentația este adesea limitată la fișiere text, atunci când este creată de persoane sau grupuri mici de programatori sau comunități. Dar, până la crearea unei documentații simple folosind un document simplu fișier text README.md (sau .txt) poți să ai cele mai bune sau bune practici, sfaturi sau ghid util de creație pentru a aduce terților cele mai complete și detaliate informații necesare despre ceea ce a fost creat.

Pentru articolul nostru, am luat Cele mai bune practici conceput și dezvăluit de Cod pentru inițiativă de dezvoltareMatei 22:21 del Banca Inter-Americană de Dezvoltare, care pe scurt ne spune că o documentație bună bazată pe un fișier text README.md (sau .txt) Acesta trebuie structurat după cum urmează:

Structura fișierului README recomandată

• Descriere și context: Secțiune în care trebuie să descrieți funcționalitățile, contextul în care a fost dezvoltat și problemele de dezvoltare pe care le-a ajutat să le rezolve.
• Ghidul utilizatorului: Secțiune în care trebuie menționate instrucțiunile către utilizatorul final cu privire la modul de a începe utilizarea instrumentului digital.
• Ghid de instalare: Secțiune în care trebuie menționate instrucțiunile de instalare pentru reutilizarea și configurarea instrumentului digital. Această secțiune este destinată dezvoltatorilor.
• autori Secțiune în care trebuie acordate credite colaboratorilor instrumentului.
• Licență pentru codul instrumentului: Secțiune în care trebuie specificate permisiunile acordate terților pentru reutilizarea instrumentului digital.
• Licență pentru documentarea instrumentului: Secțiune în care trebuie menționat tipul de licență cuprins în documentația creată.

În acestea bune practici, de asemenea, recomandă adăugarea la Documentația fișierului README pentru ao face mai completă, următoarele secțiuni:

• Cum să contribuiți: Secțiune care explică noilor dezvoltatori procesul de contribuție la proiecte.
• Cod de conduită: Secțiunea care explică codul de conduită stabilește normele sociale, regulile și responsabilitățile pe care indivizii și organizațiile trebuie să le urmeze atunci când interacționează în orice mod cu instrumentul digital sau cu comunitatea lor.
• Insigne: Secțiunea care arată insignele (imagini mici încorporate în README.md) care specifică într-un mod lizibil și concis starea instrumentului.
• Versiune: Secțiune care indică o listă a versiunilor instrumentului digital și a funcționalităților adăugate fiecărei versiuni.
• Mulțumiri: Secțiune care conține recunoștințele către alte persoane sau organizații care au contribuit într-un fel la proiect.

Pentru a extinde aceste informații, pe Cele mai bune practici în materie de documentație pentru dezvoltarea Software-ul gratuit, langa Cod pentru inițiativă de dezvoltareMatei 22:21 del Banca Inter-Americană de Dezvoltare puteți face clic pe următorul link: Documentare - Ghid pentru publicarea instrumentelor digitale. Și în alte publicații vom explora partea la care se referă bune practici pe evaluare și licențiere del Software gratuit și deschis înșiși.

Concluzie

Noi sperăm asta acest puțină postare utilăMatei 22:21 pe «Buenas prácticas» în domeniul «documentación» pentru a crea atunci când se dezvoltă «Software libre y abierto», să fie de mare interes și utilitate, pentru întreg «Comunidad de Software Libre y Código Abierto» și de mare contribuție la difuzarea minunatului, gigantului și creșterii ecosistemului de aplicații pentru și pentru «GNU/Linux».

Și pentru mai multe informații, nu ezitați întotdeauna să vizitați oricare Biblioteca online ca OpenLibra y jedit a citi cărți (PDF-uri) pe acest subiect sau altele domenii de cunoaștere. Deocamdată, dacă ți-a plăcut asta «publicación», nu înceta să-l împărtășești cu alții, în dumneavoastră Site-uri web preferate, canale, grupuri sau comunități de rețele sociale, de preferință gratuite și deschise ca Mastodont, sau sigur și privat, cum ar fi Telegramă.

Sau pur și simplu vizitați pagina noastră principală la DesdeLinux sau alăturați-vă canalului oficial Telegrama de DesdeLinux pentru a citi și a vota pentru această sau alte publicații interesante pe «Software Libre», «Código Abierto», «GNU/Linux» și alte subiecte legate de «Informática y la Computación», și «Actualidad tecnológica».