Osvedčené postupy na vývoj slobodného a otvoreného softvéru: Dokumentácia

La dokumentácia je a má byť základnou súčasťou dohody tvorivý proces a plánovanie všetkej ľudskej činnosti a viac v technologickej oblasti, najmä v oblasti Vývoj softvéru.

El účel celej dokumentácie musí to byť On učiť tretie strany (používateľov, správcov, správcov alebo iných vývojárov), ktorí zvyčajne nie sú oboznámení s výrobok (kód, aplikácia alebo systém), ako sa vytvára jeho štruktúra, fungovanie a ak je to možné, dôvod jeho vytvorenia a spôsob jeho návrhu a fungovania.

Ďalej v konkrétnom prípade Dokumentácia softvéru zadarmo je nevyhnutná, pretože umožňuje plne zaručiť prenos vedomostí a posilnenie postavenia nevyhnutné na uspokojivé splnenie 4 slobody ním podporované, ktorými sú:

• 0: Sloboda spustiť program, ako chcete, na akýkoľvek účel.
• 1: Sloboda prístupu a štúdia programu a zmena alebo prispôsobenie pre váš vlastný prospech.
• 2: Sloboda zdieľania alebo redistribúcie kópií s cieľom ich šírenia a / alebo pomoci iným.
• 3: Sloboda distribuovať kópie vašich upravených verzií tretím stranám.

Dobrá dokumentácia preto umožňuje, aby vytvorený produkt:

• Používa sa správne a ľahšie sa dá naučiť a naučiť sa.
• Tí, ktorí si to želajú upraviť, aby ste ich vylepšili alebo prispôsobili, musia byť dôkladne pochopení.
• Zdieľajte a prijímajte s väčšou dôverou medzi všetkými potenciálnymi známymi a neznámymi ľuďmi.
• Majte lepšiu masu medzi verejnosťou.

Osvedčené postupy: Dokumentácia

Fundamentos

V prípade Vývoj slobodného softvéru a otvoreného zdroja, všeobecne, hlavných používateľov dokumentácie pokiaľ ide o dizajn produktu, sú tie, ktoré sú alebo budú, zodpovedný za údržbu toho istého. A bez dobrej alebo žiadnej dokumentácie je jedinou životaschopnou alternatívou priame preskúmanie a dosiahnutie pochopiť jeho dizajn a funkciu.

Nevytvára dobrú dokumentáciu, pokiaľ ide o vyvíjať slobodný softvér, otvorený zdroj alebo akýkoľvek iný typ softvéru, je poslať jeho možným príjemcom (používatelia, správcovia, správcovia alebo iní vývojári) nájsť cestu džungľou bez mapy alebo kompasu.

Pre každého vytvorte kvalitnú dokumentáciu Slobodný softvér, otvorený zdroj je to tiež prospešné, pretože hoci dokumentácia má svoje nákladyAk sa investícia vykoná správne, stojí za to. Pretože, svet Softvér je plný príbehov o pôvodné kódy staré alebo súčasné programy, aplikácie alebo systémy, na ktoré si trúfne len málokto, pretože takmer nikto nechápe. Programátori sa zameriavajú na vytváranie kódu a nie na jeho správne a úplné zdokumentovanie. A toto treba napraviť.

Osvedčené postupy týkajúce sa dokumentácie v textových súboroch README

V prípade Slobodný softvér a otvorený zdroj„Dokumentácia sa často obmedzuje na textové súbory, keď ju vytvárajú jednotlivci alebo malé skupiny programátorov alebo komunity. Ale až do vytvorenia jednoduchej dokumentácie pomocou jednoduchého textový súbor README.md (alebo .txt) môžete mať svoje osvedčených postupov, tipy alebo užitočný sprievodca tvorbou, ktorý má tretím stranám poskytnúť najkompletnejšie a najpodrobnejšie informácie o vytvorenom dokumente.

Pre náš článok sme vzali Osvedčené postupy koncipovaný a zverejnený "Kódex pre rozvojovú iniciatívu" del Medziamerická rozvojová banka, ktorý nám v súhrne hovorí, že dobrá dokumentácia založená na a textový súbor README.md (alebo .txt) Musí mať nasledujúcu štruktúru:

Odporúčaná štruktúra súborov README

• Popis a kontext: Časť, v ktorej musíte opísať funkčnosť, kontext, v ktorom bola vyvinutá, a vývojové problémy, ktoré pomohla vyriešiť.
• Návod na použitie: Časť, v ktorej je potrebné spomenúť pokyny pre koncového používateľa, ako začať používať digitálny nástroj.
• Návod na inštaláciu: Časť, v ktorej je potrebné spomenúť inštalačné pokyny na opätovné použitie a konfiguráciu digitálneho nástroja. Táto časť je určená pre vývojárov.
• autori Sekcia, v ktorej musia byť spolupracovníkom nástroja poskytnuté kredity.
• Licencia pre kód nástroja: Oddiel, v ktorom je potrebné špecifikovať povolenia udelené tretím stranám na opätovné použitie digitálneho nástroja.
• Licencia na dokumentáciu k nástroju: Oddiel, kde je potrebné uviesť typ preukazu obsiahnutého vo vytvorenej dokumentácii.

V týchto osvedčených postupov, odporúčajú tiež pridať do súboru Dokumentácia k súboru README aby to bolo úplnejšie, nasledujúce sekcie:

• Ako prispieť: Sekcia, ktorá vysvetľuje novým vývojárom postup prispievania k projektom.
• Zásady správania sa: Oddiel, ktorý vysvetľuje kódex správania, stanovuje sociálne normy, pravidlá a povinnosti, ktoré musia jednotlivci a organizácie dodržiavať pri akejkoľvek interakcii s digitálnym nástrojom alebo ich komunitou.
• Odznaky: Časť zobrazujúca odznaky (malé obrázky vložené do súboru README.md), ktoré čitateľným a výstižným spôsobom určujú stav nástroja.
• Verzia: Oddiel, ktorý označuje zoznam verzií digitálneho nástroja a funkcií pridaných ku každej verzii.
• Poďakovanie: Časť, ktorá obsahuje poďakovanie ostatným ľuďom alebo organizáciám, ktoré nejakým spôsobom prispeli k projektu.

Ak chcete rozšíriť tieto informácie, na Osvedčené postupy vo veciach dokumentácia pre rozvoj slobodný softvér, tým, že "Kódex pre rozvojovú iniciatívu" del Medziamerická rozvojová banka môžete kliknúť na nasledujúci odkaz: Dokumentácia - Sprievodca publikovaním digitálnych nástrojov. A v ďalších publikáciách preskúmame príslušnú časť osvedčených postupov na hodnotenie a licencovanie del Slobodný a otvorený softvér sami.

Záver

V to dufame tento "užitočný malý príspevok" na «Buenas prácticas» v oblasti «documentación» vytvárať pri vývoji «Software libre y abierto», byť veľkým záujmom a užitočnosťou pre celú spoločnosť «Comunidad de Software Libre y Código Abierto» a je veľkým prínosom pre šírenie nádherného, ​​gigantického a rastúceho ekosystému aplikácií pre a pre «GNU/Linux».

A pre viac informácií neváhajte vždy navštíviť ktorúkoľvek z nich Online knižnica ako OpenLibra y jedit čítať knihy (PDF) na túto tému alebo iné vedomostné oblasti. Zatiaľ, ak sa vám to páčilo «publicación», neprestávaj to zdieľať s ostatnými, vo vašom Obľúbené webové stránky, kanály, skupiny alebo komunity sociálnych sietí, najlepšie bezplatné a otvorené ako Mastodon, alebo bezpečné a súkromné ​​ako telegram.

Alebo jednoducho navštívte našu domovskú stránku na adrese DesdeLinux alebo sa pripojte k oficiálnemu kanálu Telegram z DesdeLinux čítať a hlasovať za túto alebo iné zaujímavé publikácie o «Software Libre», «Código Abierto», «GNU/Linux» a ďalšie témy súvisiace s «Informática y la Computación»a «Actualidad tecnológica».