Dokumentácia je nevyhnutnou súčasťou cyklu vývoja softvéru. Vysvetľuje, ako používať softvér, a môže obsahovať používateľské príručky, odkazy na rozhranie API, pokyny na inštaláciu a poznámky k vydaniu.
Automatizácia dokumentácie je najnovším trendom, pretože môže pomôcť ušetriť čas, znížiť chyby a zabezpečiť konzistentnosť. Udržiavanie vašej dokumentácie aktuálne a prístupné všetkým zainteresovaným stranám uľahčuje spoluprácu a neustále zlepšovanie.
Dokumenty ako kód predstavujú prístup k automatizácii dokumentácie, ktorý považuje technickú dokumentáciu za kód.
Čo sú dokumenty ako kód?
Dokumenty ako kód je filozofia vývoja softvéru, ktorá považuje technickú dokumentáciu za formu kódu. Navrhuje, aby ste s dokumentáciou zaobchádzali rovnako prísne ako so softvérovým kódom.
Myšlienkou dokumentov ako kódu je zaobchádzať s dokumentáciou ako s prvotriednym artefaktom vývojového procesu a integrovať ho do životného cyklu softvéru. To znamená považovať dokumentáciu za neoddeliteľnú súčasť kódovej základne. Znamená to aplikovať naň rovnaké procesy riadenia verzií, nepretržitej integrácie a testovania, ktoré robíte na samotný kód.
V typickom nastavení dokumentov ako kód píšete dokumentáciu v obyčajných textových súboroch, zvyčajne v ľahký značkovací jazyk ako Markdown, HTML alebo reStructuredText. Potom ho uložíte do rovnakého úložiska ako zdrojový kód. To uľahčuje správu a sledovanie zmien softvéru aj dokumentácie. Pomáha tiež zabezpečiť, aby bola dokumentácia aktuálna s najnovšou verziou kódu.
Prečo by ste mali používať dokumenty ako kód
Pred dokumentmi ako kódom sa dokumentácia často považovala za oddelenú od kódu a vytvárala sa pomocou rôznych nástrojov a procesov. Tento voľnejší prístup často viedol k zastaranej dokumentácii a nezrovnalostiam s kódom. Osvojením si dokumentov ako kódového prístupu môžete využiť niekoľko výhod.
Vylepšená spolupráca
Dokumenty ako kód umožňujú spoluprácu medzi vývojármi, technickými autormi a ďalšími zainteresovanými stranami v procese vývoja. Keďže v úložisku kódu je uložená dokumentácia, je pre rôzne strany jednoduché prispievať a vykonávať zmeny. Pomáha to zabezpečiť, aby bola dokumentácia presná, aktuálna a komplexná.
Spoločný prístup k dokumentácii pomáha zabezpečiť, že obsahuje všetky relevantné informácie a že presne odráža softvérový systém, ako ho interpretujú všetky strany.
Automatizácia procesov a dostupnosť
Ďalšou výhodou dokumentov ako kódu je, že umožňuje automatizovaným nástrojom generovať a publikovať dokumentáciu. Zostavovací systém dokáže automaticky generovať HTML alebo PDF verzie dokumentácie z obyčajných textových súborov na publikovanie na webe alebo internom dokumentačnom portáli. Vďaka tomu je dokumentácia prístupná viacerým zainteresovaným stranám.
Automatizáciou procesu generovania a publikovania dokumentácie dokumenty ako kód pomáhajú skrátiť čas a úsilie potrebné na údržbu a publikovanie dokumentácie. Umožňuje vývojovým tímom sústrediť sa na zlepšovanie softvéru.
Kontrola verzií
Uloženie dokumentácie v rovnakom úložisku kódu ako softvér uľahčuje správu a sledovanie zmien v oboch.
Môžeš použiť systémy na správu verzií ako Git, aby ste mohli sledovať zmeny dokumentácie a v prípade potreby sa vrátiť k predchádzajúcim verziám. To pomáha zaistiť, že dokumentácia je presná a aktuálna, a môžete sledovať a kontrolovať zmeny.
Typický pracovný postup dokumentov ako kódu
Typický pracovný postup dokumentov ako kódu zahŕňa písanie, správu verzií, vytváranie a hosťovanie:
Proces písania
Proces písania je prvou fázou typického pracovného toku dokumentov ako kódu. Väčšina technických spisovateľov a dokumentační inžinieri používajú jednoduchý MarkDown, AsciiDoc alebo HTML. Dokumentáciu píšu pomocou nástrojov ako GitBook a Redocly, ktoré zabezpečujú hladký proces.
Kontrola verzií pre dokumentáciu
Dokumentácia sa vyvíja tak, ako sa vyvíja kód. Na sledovanie zmien dokumentácie pre jednoduchšiu spoluprácu a sledovanie verzií budete potrebovať sofistikovaný systém správy verzií, ako je Git, Plastic SCM alebo Subversion.
Proces tvorby dokumentácie
Proces zostavenia zahŕňa spracovanie a zostavenie dokumentácie do jej doručovacích formátov. Môžu to byť HTML, PDF, EPUB alebo iné. Proces dokumentácie je zvyčajne jednoduchší pomocou generátorov statických stránok, ako sú Hugo a Jekyll.
Hosting a distribúcia dokumentácie
Proces hosťovania alebo distribúcie je zvyčajne posledným krokom dokumentov ako procesu kódovania. Tento proces zabezpečuje, že dokumentácia je doručená koncovému používateľovi a dostupná všetkým zainteresovaným stranám. Na distribúciu dokumentácie na webe môžete použiť stránky GitHub alebo GitLab alebo vlastný portál.
Dokumentáciu Go a Java môžete automatizovať pomocou GoDoc a JavaDoc
Dokumenty ako filozofia kódu prináša revolúciu v písaní a správe technickej dokumentácie.
Mnoho programovacích jazykov, vrátane Go a Java, poskytuje nástroje na automatizáciu dokumentácie pomocou komentárov kódu. Go poskytuje nástroj Godoc a Java poskytuje JavaDoc.