Formální stránka
- Identifikace příkladu (krátký název)
- Identifikace autora, včetně určení skupiny (podle rozdělení v ReCodexu)
- Text je naformátován tak, aby byla zřejmá jeho struktura
- Text splňuje základní typografická pravidla hladké sazby (nepište spojovník, kde má být pomlčka, ap.)
Dokumentace by měla mít tyto části (doporučuji dodržet i toto pořadí)
- Zadání odsouhlasené cvičícím
- Podrobná specifikace, která vznikla zpřesňováním prvotního zadání během práce na programu
- Návod pro použití programu, případně i vzorová vstupní data. Jeden vhodně zvolený příklad vstupních dat, může výrazně usnadnit sepisování návodu
- Výběr algoritmu a diskuse o výhodách/nevýhodách zvoleného řešení
- Programátorská dokumentace, to znamená popis pro programátora (zhruba se stejnými zkušenostmi, jako jste vy), který si z tohoto textu udělá obrázek, jakým způsobem jste úlohu řešili, aniž by musel studovat přímo kód.
S pomocí prográmatorské dokumentace musí být schopen jiný programátor upravovat a rozšiřovat váš program.
Součástí programátorské dokumentace jsou i komentáře v programu, ale jsou pouze jejím důležitým doplňkem, nikoliv klíčovou částí
Rada: Začněte popisem klíčových datových struktur. Pokud popisujete důležité podprogramy, uvádějte jejich hlavičky včetně parametrů. Text bude výrazně přehlednější, čitelnější a bude se vám i snáze psát.
- Závěr – osobní postřehy a zhodnocení, co jsem se naučil, co mi nešlo, co bylo těžké, co mě překvapilo, ...
- Testovací data – nemusí být (ale pokud je to vhodné, tak ano) přímo součástí textové dokumentace, jinak testovací soubory stačí odevzdat společně s programem
Pro inspiraci doporučuji k přečtení text dr. Kryla o psaní dokumentace.