Dokumentace k softwaru
Dokumentace k softwaru je v informatice psaný text, který doprovází počítačový software. Popisuje jak software pracuje nebo jak se používá. Jejím účelem je usnadnit práci s novým produktem či technologií.
Části dokumentace[editovat | editovat zdroj]
Dokumentace je důležitá část softwarového inženýrství, kterou lze rozdělit na různé části:
- Dokumentace požadavků – Prohlášení, která identifikují atributy, schopnosti nebo vlastnosti systému. Tvoří základ pro to, co bylo nebo bude realizováno.
- Dokumentace architektury/designu – Přehled softwaru. Zahrnuje vztahy k prostředí a stavebním základům, které budou použity v návrhu softwarových komponent.
- Technická dokumentace – Dokumentace kódu, algoritmy, popis rozhraní a API.
- Uživatelská dokumentace – Manuály pro koncového uživatele, systémové administrátory a osazenstvo podpory.
- Marketingová dokumentace – Jak prodávat produkt a analýza tržní poptávky.
Dokumentace požadavků[editovat | editovat zdroj]
Dokumentace požadavků je popis toho, co konkrétní software dělá nebo musí dělat. Především se využívají při vývoji a slouží jako základní informace, pro to, co software má dělat. Dokumentace požadavků je výsledkem práce lidí, kteří se podílejí na výrobě softwaru: koncoví uživatelé, zákazníci, produktoví manažeři, projektoví manažeři, prodej, marketing, softwaroví architekti, inženýři, návrháři, vývojáři a lidé, co tyto softwary testují.
- Požadavky se přijímají v různých stylech zápisu, např.
- konkrétní (např. distribuované pracovní prostředí)
- designové (např. funkci postavit – lze spustit kliknutím pravým tlačítkem na konfigurační soubor a vybrat položku „postavit“)
- možnost specifikace v přirozeném jazyce, pomocí matematických rovnic nebo kombinací různých zápisů
Varianty a složitost požadavků jsou variabilní a mohou být pevně dané, ale i postupně dodávány. Ve většině případů je těžké odhadnout, kolik lidí a jaký druh dokumentace je zapotřebí. Na dokumentaci požadavků se podílí více osob, proto je často neúplná nebo nekompletní. Bez řádné dokumentace požadavků se změny v softwaru těžko hledají a vy softwaru může dojít k chybám (snížená softwarová kvalita). Potřeba požadavků na dokumentaci souvisí se složitostí produktu, dopadu produktu a průměrnou délkou životnosti softwaru. Jestliže je software složitější nebo vyvíjen více lidmi, požadavky mohou lépe sdělit cíle softwaru (např. software pro mobilní telefony). U softwarů, které mohou mít negativní vliv na životní prostředí, je často dokumentace vyžadována (např. systémy jaderné energie, lékařské vybavení). Požadavky jsou specifikovány v dokumentech požadavků (např. použití tabulkových a textových editorů).
Architektura/Design dokumentace[editovat | editovat zdroj]
Dokumentace architektury je zvláštní druh dokumentu. Architektura dokumentu je třetí částí odvozenou z kódu (druhou částí je návrh dokumentu a první je kód). Tyto dokumenty nepopisují, jak se program chová v praxi, ale pouze všeobecná ustanovení. Dobrá dokumentace je krátká a výstižná.
Další částí je dokumentace designu. Zabývá se porovnáváním dokumentů nebo obchodní studií, která má často podobu Bílé knihy. Zaměřuje se na jeden specifický aspekt systému a navrhuje alternativní přístupy. Může obsahovat uživatelské rozhraní, kód, design nebo také architektonické úrovně. Tyto aspekty popisují jednu nebo více alternativ pomocí kladů a záporů. Dokumentace o obchodní studii je velmi náročná na výzkum, myšlenky vyjadřuje jasně a výstižně, je nestranná. Cílem obchodní studie je navrhnout nejlepší řešení a vysvětlit jednotlivé nákladové položky.
Důležitou součástí návrhu dokumentu ve vývoji podnikového softwaru je Databázový Design Dokument (DDD), který obsahuje konceptuální, logický a fyzický návrh.
Technická dokumentace[editovat | editovat zdroj]
Technická dokumentace vzniká současně při tvorbě softwaru. Samotný zdrojový kód je totiž nedostatečný. Spolu s kódem musí být psán doprovodný text, který popisuje jednotlivé činnosti programu. Dokument musí být důkladný, ale nemusí zacházet do podrobností (obtížná údržba). Některé dokumentace softwarových aplikací nebo softwarových produktů jsou k nalezení na stránkách API. Tyto stránky využívají vývojáři, testeři i koncoví uživatelé. V dnešní době se vyvíjí rozsáhlé softwary, které by se bez této dokumentace neobešly. K návrhu dokumentace se využívají nástroje, jako Doxygen, NDoc, javadoc, EiffelStudio, Sandcastle, ROBODoc, POD, TwinText nebo může být využité „automatické generování dokumentu“, které vypíše připomínky a kontraktové programování a vytvoří z nich text nebo HTML soubor. Kód dokumentu je organizován do referenční příručky a umožňuje rychlé hledání.
Uživatelská dokumentace[editovat | editovat zdroj]
Na rozdíl od technické dokumentace je uživatelská dokumentace obvykle psána jednodušeji, aby bylo pro obyčejného uživatele jasné, co program dělá. V případě softwarových knihoven se může dokument podobat technické dokumentaci. Dokumentace obsahuje popis všech funkcí programu a pomáhá uživateli při jejich používání, je stále aktualizována a psána tak, aby dokázala pomoci uživateli při řešení problémů.
- Způsoby psaní technické dokumentace
- Tutorial
- Tematicky
- List nebo odkaz
Marketingová dokumentace[editovat | editovat zdroj]
Pro mnoho aplikací je nutné mít propagační materiály, které seznámí potenciální uživatele se základními vlastnostmi aplikace a přinutí je aplikaci si pořídit. Tato část dokumentace se skládá ze tří částí:
- Seznámit potenciální zákazníky s produktem a vnutit jim myšlenku, aby byli s produktem co nejvíce v kontaktu
- Informovat zákazníky, co přesně produkt dělá
- Vysvětlit postavení produktu, pokud jde o jinou alternativu
Externí odkazy[editovat | editovat zdroj]
Obrázky, zvuky či videa k tématu dokumentace k softwaru na Wikimedia Commons
