Dokumentace je nezbytnou součástí cyklu vývoje softwaru. Vysvětluje, jak používat software, a může zahrnovat uživatelské příručky, odkazy na rozhraní API, pokyny k instalaci a poznámky k verzi.
Automatizace dokumentace je nejnovějším trendem, protože může pomoci ušetřit čas, omezit chyby a zajistit konzistenci. Udržování vaší dokumentace aktuální a přístupné všem zainteresovaným stranám usnadňuje spolupráci a neustálé zlepšování.
Dokumenty jako kód představují přístup k automatizaci dokumentace, který zachází s technickou dokumentací jako s kódem.
Co jsou dokumenty jako kód?
Dokumenty jako kód jsou filozofií vývoje softwaru, která pohlíží na technickou dokumentaci jako na formu kódu. Navrhuje, abyste s dokumentací zacházeli se stejnou přísností a procesem jako se softwarovým kódem.
Smyslem dokumentu jako kódu je zacházet s dokumentací jako s prvotřídním artefaktem vývojového procesu a integrovat jej do životního cyklu softwaru. To znamená považovat dokumentaci za nedílnou součást kódové základny. Znamená to, že na něj použijete stejné procesy řízení verzí, průběžné integrace a testování, které provádíte na samotný kód.
V typickém nastavení kódu dokumentů píšete dokumentaci do souborů ve formátu prostého textu, obvykle v lehký značkovací jazyk, jako je Markdown, HTML nebo reStructuredText. Poté jej uložíte do stejného úložiště jako zdrojový kód. To usnadňuje správu a sledování změn softwaru i dokumentace. Pomáhá také zajistit, aby dokumentace byla aktuální s nejnovější verzí kódu.
Proč byste měli používat dokumenty jako kód
Než se dokumenty staly kódem, dokumentace byla často považována za oddělenou od kódu, vytvořená pomocí různých nástrojů a procesů. Tento volnější přístup často vedl k zastaralé dokumentaci a nesrovnalostem s kódem. Přijetím přístupu k dokumentům jako kódu můžete využít několik výhod.
Vylepšená spolupráce
Dokumenty jako kód umožňují spolupráci mezi vývojáři, technickými autory a dalšími zainteresovanými stranami v procesu vývoje. Vzhledem k tomu, že v úložišti kódu je uložena dokumentace, je pro různé strany snadné přispívat a provádět změny. To pomáhá zajistit, že dokumentace je přesná, aktuální a komplexní.
Kolaborativní přístup k dokumentaci pomáhá zajistit, aby obsahovala všechny relevantní informace a aby přesně odrážela softwarový systém, jak jej interpretují všechny strany.
Automatizace procesů a dostupnost
Další výhodou dokumentů jako kódu je to, že umožňuje automatizovaným nástrojům generovat a publikovat dokumentaci. Sestavovací systém může automaticky generovat HTML nebo PDF verze dokumentace ze souborů prostého textu pro publikování na webové stránky nebo na interní dokumentační portál. Dokumentace je tak přístupná více zúčastněným stranám.
Automatizací procesu generování a publikování dokumentace pomáhá dokumenty jako kód zkrátit čas a úsilí potřebné k údržbě a publikování dokumentace. Umožňuje vývojovým týmům soustředit se na zlepšování softwaru.
Kontrola verzí
Uložení dokumentace ve stejném úložišti kódu jako software usnadňuje správu a sledování změn obou.
Můžeš použít systémy pro správu verzí jako Git pro sledování změn dokumentace a v případě potřeby se vracet k předchozím verzím. To pomáhá zajistit, že dokumentace je přesná a aktuální, a můžete sledovat a kontrolovat změny.
Typické dokumenty jako pracovní postup kódu
Typický pracovní postup pro dokumenty jako kód zahrnuje psaní, správu verzí, vytváření a hostování:
Proces psaní
Proces psaní je první fází typického pracovního postupu dokumentů jako kódu. Většina techničtí spisovatelé a dokumentační inženýři používají jednoduché MarkDown, AsciiDoc nebo HTML. Dokumentaci píší pomocí nástrojů jako GitBook a Redocly, které zajišťují hladký proces.
Řízení verzí pro dokumentaci
Dokumentace se vyvíjí s tím, jak se vyvíjí kód. Budete potřebovat sofistikovaný systém správy verzí, jako je Git, Plastic SCM nebo Subversion, abyste mohli sledovat změny v dokumentaci pro snazší spolupráci a sledování verzí.
Proces sestavení dokumentace
Proces sestavení zahrnuje zpracování a sestavení dokumentace do formátů dodávky. Mohou to být HTML, PDF, EPUB nebo jiné. Proces dokumentace je obvykle usnadněn pomocí generátorů statických stránek, jako jsou Hugo a Jekyll.
Hosting a distribuce dokumentace
Proces hostování nebo distribuce je obvykle posledním krokem dokumentu jako procesu kódování. Tento proces zajišťuje, že dokumentace je doručena koncovému uživateli a dostupná všem zúčastněným stranám. K distribuci dokumentace na webu můžete použít stránky GitHub nebo GitLab nebo vlastní portál.
Dokumentaci Go a Java můžete automatizovat pomocí GoDoc a JavaDoc
Dokumenty jako filozofie kódu přináší revoluci v psaní a správě technické dokumentace.
Mnoho programovacích jazyků, včetně Go a Java, poskytuje nástroje pro automatizaci dokumentace pomocí komentářů ke kódu. Go poskytuje nástroj Godoc a Java poskytuje JavaDoc.
