LIMSwiki

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í.

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ů 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ů).

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 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í.

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

1. Tutorial
2. Tematicky
3. List nebo odkaz

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í:

1. Seznámit potenciální zákazníky s produktem a vnutit jim myšlenku, aby byli s produktem co nejvíce v kontaktu
2. Informovat zákazníky, co přesně produkt dělá
3. Vysvětlit postavení produktu, pokud jde o jinou alternativu

• Obrázky, zvuky či videa k tématu dokumentace k softwaru na Wikimedia Commons