Shrnutí na Softwarová dokumentace a její principy

## Úvod Dokumentace softwaru popisuje informace potřebné k pochopení, používání a údržbě softwarového produktu. Cílem tohoto materiálu je předat přehled účelu dokumentace, jakou formu může mít, jaké standardy a nástroje se používají a jak dokumentaci efektivně tvořit a znovupoužívat. > Definice: Dokumentace softwaru jsou organizované artefakty (návody, popisy architektury, uživatelské příručky, apod.) vytvářené za účelem předání znalostí o softwarovém produktu různým zainteresovaným stranám. ## Proč dokumentujeme software - Podpora testování a ověřování funkčnosti systému. - Podpora údržby a rozvoje (znalost architektury, rozhraní, pravidel komunikace). - Podpora koncových uživatelů (návody, tutoriály, FAQ). - Právní a smluvní požadavky (dodání dokumentace může být součástí kontraktu). > Definice: Uživatelská dokumentace je soubor materiálů určený koncovým uživatelům, který popisuje, jak systém používat. ### Kdo dokumentaci potřebuje - Testeři — reprodukce požadavků a testovacích případů. - Vývojáři a tým údržby — porozumění návrhu a závislostem. - Manažeři projektu — sledování rozsahu a shody se standardy. - Zákazníci — provozní a uživatelské instrukce. ## Forma dokumentace Formu volíme podle velikosti projektu, složitosti, distribuovanosti týmu a očekávaného uživatele. - Krátké interní poznámky a komentáře vs. formální příručky. - Tištěná vs. elektronická dokumentace (prohledatelnost, navigace, odkazy). - Živá dokumentace integrovaná s kódem (automaticky generovaná) vs. ručně psaná. > Definice: Elektronická dokumentace je dokumentace distribuovaná v elektronickém formátu, která umožňuje navigaci, hypertextové odkazy a vyhledávání. ### Příklady forem - Uživatelské příručky a tutoriály. - Referenční manuály k API (generované z kódu pomocí nástrojů). - Architektonické přehledy a diagramy. - Chybové a servisní příručky. ## Struktura uživatelské dokumentace (podle dobrých praktik) - Úvod a účel. - Požadavky na systém (instalační podmínky). - Základní scénáře použití (návody krok za krokem). - Detailní popis funkcí a omezení. - FAQ a odstraňování chyb. | Komponenta | Účel | Příklad obsahu | |---|---:|---| | Úvod | Seznámit čtenáře s cílem dokumentu | Popis cílové skupiny a rozsahu | | Instalace | Pomoci s nasazením | Požadavky HW/SW, kroky instalace | | Uživatelské scénáře | Naučit běžné úkony | Krok za krokem operace | | Chybová hlášení | Pomoci při řešení problémů | Seznam chyb a doporučené kroky | Fun fact: Dokumentace, která je dobře navržená a integrovaná s procesem vývoje, snižuje čas potřebný pro onboardování nových členů týmu až o desítky procent. ## Standardy a doporučení - IEEE 1063 (zahrnuje minimální požadavky na uživatelskou dokumentaci, pokrývá i elektronické formy). - Doporučení zahrnují požadavky, že dokumentace musí být kompletní, přesná, jednoznačně identifikovatelná a vhodná pro konkrétní účely (tutoriály, uživatelská dokumentace, chybová hlášení). > Definice: IEEE 1063 je standard, který definuje minimální strukturu, obsah a formát uživatelské dokumentace softwaru. ### Co standard IEEE 1063 doporučuje - Jasné určení rozsahu a cílové skupiny. - Definice významných pojmů (kritické informace, ilustrace, uživatel). - Doporučení pro organizaci obsahu a navigaci v elektronických dokumentech. ## Nástroje a automatizace - Generátory dokumentace z komentářů v kódu (automatické extrakce referencí). - Systémy pro správu obsahu (CMS) a wiki pro živou, společně upravovanou dokumentaci. - Nástroje pro tvorbu diagramů a modelů architektury. ### Praktické tipy pro efektivní dokumentaci 1. Znovupoužijte existující artefakty: use-case scénáře, testovací případy, komentáře v kódu. 2. Dokumentujte „proč“, ne jen „co“ a „jak“. 3. Udržujte dokumentaci blízko k zdrojům pravdy (kód, testy, CI/CD). 4. Používejte šablony a standardizované formáty. 5. Určete vlastníka dokumentace a pravidla pro aktualizaci. > Definice: Znovupoužití dokumentace znamená převést existující texty (např. scénáře) do ji