Dokumentace k softwaru

Z Wikipedie, otevřené encyklopedie
Skočit na: Navigace, Hledání

Dokumentace k softwaru nebo dokumentace zdrojového kódu 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, vlastnosti 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
  1. Tutorial
  2. Tematicky
  3. List nebo odkaz

Marketingová dokumentace[editovat | editovat zdroj]

Pro mnoho aplikací je nutné mít propagační materiály, které seznámí potencioná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