Dokumentace má formulovat zadání problému a popsat způsob řešení a výsledek, tj. program. Má dovolit někomu jinému nebo Vám po větším časovém odstupu pochopit filozofii a způsob použití programu a dovolit program udržovat a rozvíjet. Dokumentaci píšete pro výukové účely, i jako přípravu na diplomovou či bakalářskou práci. Proto by měla prokázat v analytické části Vaši "informatickou dovednost", tj schopnost rozebrat možná řešení a zdůvodnit Vámi vybraná.
Dokumentace má formu souvislého textu. Neobsahuje jednotlivé body jako slajdy, ani to nejsou vybrané komentáře z programu. Neberte si příklad z firemních dokumentací. Příliš technické věci nepatří do dokumentace, ale do komentářů k programu. "Technické" části, které chcete uvést, dejte do příloh. Mezi ně patří např. popis interface a jím predávané datové struktury, seznam chyb nebo formální popis (gramatiky) vstupu. Pokud je program menu-driven, svádí to psát i dokumentaci tímto způsobem. Na začátku by ale měla být filozofie systému a ovládání. Jednotlivé funkce pak v pořadí podle důležitosti, použitelnosti nebo jednoduchosti, ne podle polohy v menu zlevohora pravodolu.
Psát o problému začnete od začátku. Používané termíny zaveďte. Nepředpokládejte, že Vaše vědomosti, předpoklady a informace má jiný uživatel. Uvedomte si, že jste nad programem (v lepším případě nad analýzou problému) strávili nejaký čas a mnohé skutečnosti či rozhodnutí se Vám staly zřejmé. Dokumentace je určena tomu, kdo ji bude číst, a z jeho hlediska by měla být napsána.
Dokumentace má obsahovat tyto části: popis problému, rozbor problému, možná řešení, popis datových struktur, algoritmu, vstupu a výstupu, programu a závěr.
Popis problému má vysvětlit, jakou úlohu řešíte a případně z jakého pohledu. Zadání dostáváte většinou vágní, podobne jako v praxi. Rozbor problému má prokázat, že jste přemýšleli, než jste začali programovat. Jeho součástí jsou možné návrhy koncepce, datových struktur a algoritmů. Končí zdůvodněním, proč bylo vybráno určité řešení.
Vyvíjíte program, který je výsledkem Vaší práce. Ale popsat by jste neměli jen ten program, jako výsledek, ale i proces přemýšlení a rozhodování. Pokud jste schopni napsat kriteria, podle kterých jste se rozhodovali, je to jen dobře.
Popis datových struktur a algoritmu by měl rozebrat podstatné rysy. Nemá to být kopie zdrojového kódu.
Popis vstupu zahrnuje popis způsobu práce a ovládání programu, syntaxi vstupních dat a vstupní omezení, tj. přípustnost dat. Příklady se taky hodí. Popis výstupu obsahuje hlavně interpretaci výsledků, co a jak se má pochopit. Tyto informace mají být i na výstupu, nejen v dokumentaci. Pokud je výstup určen pro další počítačové zpracování, pak součástí popisu je přesný popis datových struktur nebo syntaxe. Popis reakcí na chyby a chybových hlášení patří taky do této části.
Popis algoritmu nemá být závislý na programovacím jazyku. Je na vyšší úrovni abstrakce než popis programu, který obsahuje např. rozdělení do modulů či vrstev, případně popis důležitých rozhraní (interface). Popis rozhraní může obsahovat skoro všechny části jako celá dokumentace. Technické podrobnosti mají být v přílohách a/nebo v komentářích.
Závěr shrne Vaše zkušenosti, kladné i záporné. Zde patří úvahy o dalších možných rozšířeních, nedodělaných částech, chybách a nestandardních způsobech použití.
e-mail: hric@barbora.(ms.)mff.cuni.cz
URL: http://kti.ms.mff.cuni.cz/~hric/index.html
last update: ...