Osvědčené postupy pro vývoj bezplatného a otevřeného softwaru: dokumentace

La dokumentace je a měla by být základní součástí tvůrčí proces a plánování veškeré lidské činnosti a více v technologické oblasti, zejména v oblasti Vývoj softwaru.

El účel veškeré dokumentace musí to být on učit třetí strany (uživatele, administrátory, správce nebo jiné vývojáře), kteří obvykle nejsou obeznámeni s produkt (kód, aplikace nebo systém), jak se vytváří jeho struktura, jeho provoz a pokud je to možné, důvod jeho vytvoření a způsob jeho návrhu a provozu.

Navíc v konkrétním případě Dokumentace softwaru zdarma je zásadní, protože umožňuje plně zaručit přenos znalostí a zmocnění nezbytné pro uspokojivé splnění 4 svobody jím propagované, kterými jsou:

• 0: Svoboda spustit program, jakkoli chcete, za jakýmkoli účelem.
• 1: Svoboda přístupu a studia k programu a jeho změně nebo přizpůsobení pro vlastní prospěch.
• 2: Svoboda sdílet nebo redistribuovat kopie za účelem jejich šíření a / nebo pomoci ostatním.
• 3: Svoboda distribuovat kopie vašich upravených verzí třetím stranám.

Dobrá dokumentace proto umožňuje, aby vytvořený produkt:

• Používá se správně a snadněji se učí a učí.
• Být důkladně pochopen těmi, kteří si to přejí upravit, aby ho vylepšili nebo přizpůsobili.
• Buďte sdíleni a přijímáni s větší důvěrou mezi všemi možnými známými i cizími lidmi.
• Mějte lepší veřejnost.

Osvědčené postupy: Dokumentace

Základy

V případě Vývoj svobodného softwaru a otevřeného zdroje, obvykle, hlavní uživatelé dokumentace ve vztahu k designu produktu jsou ty, které jsou nebo budou, odpovědný za údržbu stejné. A bez dobré nebo žádné dokumentace je jedinou schůdnou alternativou její přímé prozkoumání a dosažení pochopit jeho design a funkci.

Nevytváření dobré dokumentace, pokud jde o vyvíjet svobodný software, otevřený zdroj nebo jakýkoli jiný typ softwaru, je odeslat svým možným příjemcům (uživatelé, správci, správci nebo jiní vývojáři) najít cestu džunglí bez mapy nebo kompasu.

Pro každého vytvořte dobrou dokumentaci Svobodný software, otevřený zdroj je to také prospěšné, protože dokumentace má své nákladyInvestice, pokud bude provedena správně, stojí za to. Protože svět Vývoj je plný příběhů o starší kódy staré nebo aktuální programy, aplikace nebo systémy, kterých se odváží dotknout jen málokdo, protože tomu téměř nikdo nerozumí. Programátoři se zaměřují na vytváření kódu a nikoli na jeho správné a úplné zdokumentování. A to musí být napraveno.

Osvědčené postupy pro dokumentaci v textových souborech README

V případě Svobodný software a otevřený zdroj„Dokumentace je často omezena na textové soubory, když je vytvářena jednotlivci nebo malými skupinami programátorů nebo komunit. Ale až do vytvoření jednoduché dokumentace pomocí jednoduchého textový soubor README.md (nebo .txt) můžete mít svůj nejlepší nebo osvědčené postupy, tipy nebo užitečný průvodce tvorbou, který třetím stranám poskytne nejúplnější a nejpodrobnější informace potřebné k tomu, co bylo vytvořeno.

Pro náš článek jsme vzali Dobré postupy koncipována a zveřejněna "Kodex pro rozvojovou iniciativu" del Interamerican Development Bank, což nám souhrnně říká, že dobrá dokumentace založená na a textový soubor README.md (nebo .txt) Musí mít následující strukturu:

Doporučená struktura souborů README

• Popis a kontext: Sekce, kde musíte popsat funkce, kontext, kde byl vyvinut, a vývojové problémy, které pomohl vyřešit.
• Uživatelská příručka: Sekce, kde je třeba zmínit pokyny pro koncového uživatele, jak začít používat digitální nástroj.
• Instalační příručka: Část, kde je třeba zmínit instalační pokyny pro opakované použití a konfiguraci digitálního nástroje. Tato část je určena pro vývojáře.
• autoři Sekce, kde musí být spolupracovníkům nástroje uděleny kredity.
• Licence pro kód nástroje: Sekce, kde je třeba specifikovat oprávnění udělená třetím stranám k opětovnému použití digitálního nástroje.
• Licence pro dokumentaci nástroje: Sekce, kde je třeba uvést typ licence obsažený ve vytvořené dokumentaci.

V nich dobré praxe, také doporučují přidat do Dokumentace souboru README aby to bylo úplnější, následující sekce:

• Jak přispět: Sekce, která vysvětluje novým vývojářům postup přispívání k projektům.
• Kodex chování: Sekce, která vysvětluje kodex chování, stanoví sociální normy, pravidla a odpovědnosti, které musí jednotlivci a organizace dodržovat při jakékoli interakci s digitálním nástrojem nebo jejich komunitou.
• Odznaky: Sekce zobrazující odznaky (malé obrázky vložené do souboru README.md), které čitelným a stručným způsobem určují stav nástroje.
• Verze: Sekce, která označuje seznam verzí digitálního nástroje a funkcí přidaných ke každé verzi.
• Poděkování: Sekce, která obsahuje poděkování dalším lidem nebo organizacím, které nějakým způsobem přispěly k projektu.

Chcete-li tyto informace rozšířit, na Dobré postupy ve věcech dokumentace pro rozvoj Svobodný softwaretím, že "Kodex pro rozvojovou iniciativu" del Interamerican Development Bank můžete kliknout na následující odkaz: Dokumentace - Průvodce publikováním digitálních nástrojů. A v dalších publikacích prozkoumáme část odkazující na dobré praxe o hodnocení a licencování del Svobodný a otevřený software oni sami.

Závěr

Doufáme, že tento "užitečný malý příspěvek" o «Buenas prácticas» v oblasti «documentación» vytvářet při vývoji «Software libre y abierto», být velkým zájmem a užitečností pro všechny «Comunidad de Software Libre y Código Abierto» a je velkým příspěvkem k šíření nádherného, ​​gigantického a rostoucího ekosystému aplikací pro a pro «GNU/Linux».

A pro více informací neváhejte vždy některou navštívit Online knihovna jak OpenLibra y jedit číst knihy (PDF) na toto téma nebo jiné znalostní oblasti. Prozatím, pokud se vám to líbilo «publicación», nepřestávej to sdílet s ostatními, ve vašem Oblíbené webové stránky, kanály, skupiny nebo komunity sociálních sítí, nejlépe zdarma a otevřených jako Mastodonnebo bezpečné a soukromé Telegram.

Nebo jednoduše navštivte naši domovskou stránku na DesdeLinux nebo se připojte k oficiálnímu kanálu Telegram z DesdeLinux číst a hlasovat pro tuto nebo jiné zajímavé publikace na «Software Libre», «Código Abierto», «GNU/Linux» a další témata související s «Informática y la Computación», A «Actualidad tecnológica».