Jak psát dokumentaci k ročníkovému projektu z programování Tomáš Obdržálek, duben 2013 Gymnázium, Praha 6, Arabská Ročníkový projekt je často prvním setkáním studenta s pří pravou uceleného odborného textu. Sestavení dokumentace po obsahové i formální stránce je důležitý krokem k získání dovednosti, kterou student uplatní na vysoké škole, v akade mické praxi i v zaměstnání. Pro mnohé je sepsání dokumentace nový úkol a neví si s ním rady – zejména neví co a jak do práce napsat a často se do pouštějí stylistických chyb i chyb ve struktuře textu. Cílem tohoto dokumentu je studentům s tímto problémem pomoci.
1. Obsah ročníkové práce Práce je rozdělena do tří částí: » úvodní část – obsahuje formální náležitosti – úvodní stranu, anotaci, zadání práce a obsah (seznam kapitol); » samotná práce včetně úvodu a závěru; » přílohy - rejstřík, seznam literatury a další.
1.1. Úvodní strana V požadavcích na ročníkový projekt je uveden seznam povinných informací, které na úvodní stránce musí být. Plný oficiální název naší školy je: „Gymnázium, Praha 6, Arabská 14“. Je možné použít logo školy, logo nebo obrázek cha rakterizující projekt. Příklad vhodného uspořádání první strany projektu:
Příklad anotace: Anotace: Cílem projektu je navržení vhodné architektu ry a technologické platformy pro systém elektronického sledování myší v rodinném domě. Součástí práce je pro totyp čidla a software pro snímání příslušných informací a jejich statistické zpracování. Práce obsahuje podrobnou dokumentaci k případné implementaci systému.
1.3. Zadání projektu Součástí dokumentace je text zadání projektu, dříve schválený vyučujícím. Je možné jej graficky sjednotit s ostatními částmi dokumentu, ale při tom nesmí dojít ke změně významu. Roz sah zadání by neměl přesáhnout 2 strany.
1.4. Samotná práce Při psaní každého textu, nejen odborného, především musíme mít co sdělit.
Struktura textu Kvalitu dokumentu významným způsobem ovlivní naše schopnost stanovit srozumitelnou strukturu textu – tedy vhodné seřazení témat (případně jejich „vnoření“) tak, aby se čtenář v textu orientoval. Několik rad: » každá kapitola by měla mít srozumitelný název vyplývající z jejího obsahu; » v jedné kapitole nespojujeme více témat; » každé téma by mělo mít v práci své místo – otevíráme i uzavíráme jej v jedné kapitole; vyhneme se přeskakování z tématu na téma a jejich „roztroušení“ v celé práci; » témata by měla na sebe srozumitelným způsobem navazovat. Příklad možné struktury: » úvod – k čemu je dobré sledovat myší; » problematika pohybu hlodavců v omezeném prostoru; » seznámení s technologií váhových a optických čidel; » diagram architektury navrženého čidla; » algoritmus sledování hlodavce mezi jednotlivými čidly; » statistické zpracování získaných dat; » závěr – zkušenosti s testováním prototypu systému. Pokud je námi navržená struktura textu něčím specifická, je vhodné na to upozornit v úvodu práce.
Návrh možných témat Ročníková práce zpravidla řeší jeden nebo více klíčových problémů. Pokud vám není jasné, o co by mělo jít, poraďte se s vyučujícím. Kresba myši převzata z http://www.openclipart.org
1.2. Anotace Anotací (anglicky abstract) rozumíme stručný popis tématu práce. Čtenář by se z anotace měl dozvědět vše důležité, aby mohl posoudit, jestli práce pro něj obsahuje zajímavé informa ce. Anotace má rozsah 300 – 1000 znaků.
Příklady: » hra piškvorky (hráč proti hráči) → vyhodnocení existence pěti ce; » hra piškvorky (hráč proti počítači) → umělá inteligence počíta če; » ruleta, poker → datová struktura pro sázky a jejich vyhodno cení; » hra deflektor (paprsek odrážený zrcadly) → vyhledání zrcadla, které stojí paprsku v cestě; » hra více hráčů → komunikace mezi instancemi programu;
Jak psát dokumentaci k ročníkovému projektu z programování
str. 1
» sledování myší → návrh čidla a algoritmus sledování cesty hlo davce; » apod. Popis řešení klíčových problémů by mělo být stěžejním téma tem práce. Program zpravidla pomáhá řešit potřeby reálné oblasti lidské činnosti – například práci knihovny, hraní karetní hry, sle dování pohybu hlodavců apod… Práce by měla problematiku krátce nastínit. Příklad: popis jak se půjčují knihy; pravidla ka retní hry; denní rytmus života hlodavce. V případě použití odborných pojmů je vhodné zařadit na za čátku práce jejich vysvětlení. Pokud je pojmů příliš mnoho, mů žeme se některým z nich vyhnout opisem. V práci uvedeme všechny technologie, které jsme použili – programovací jazyk, IDE, překladač, běhové prostředí, externí knihovny, databáze, komunikační protokoly, formáty souborů apod. Někde bude stačit krátký popis, u klíčových technologií podrobněji rozepíšeme jejich vlastnosti a způsob jak jsme je pou žili. U větších projektů může být užitečné popsat architekturu projektu – rozdělení na jednotlivé moduly (balíčky), popis jejich „odpovědností“ a technologií kterou jsou řešeny a způsob komu nikace mezi nimi. Velkou pozornost si zaslouží datové struktury – použité da tové typy a záznamy, u objektového návrhu třídy a vztahy mezi nimi (dědičnost, kompozice, rozhraní). V případě použití data bázového systému pak je vhodné popsat databázové schéma. Da tové struktury mají vzhledem k návrhu řešení a použitých algo ritmů velkou vypovídací hodnotu. Pokud je důležitou součástí naší práce zajímavý algoritmus – ať již jsme jej vytvořili sami nebo převzali – popíšeme jeho činnost a způsob jak jsme jej použili. Jestliže program nabízí vnější rozhraní (tzv. API) – například se jedná o knihovnu nebo službu dostupnou přes síť – podrobně popíšeme způsob použití. V některých případech si práce vyžádá uvést matematické výpo čty, případně znalosti z jiného vědního oboru. Tam kde to není triviální, vypíšeme požadavky na provoz sys tému, postup instalace a jednoduchou uživatelskou příruč ku.
dů mezi nimi, použijeme stavový diagram. » uživatelsky orientované systémy s více uživatelskými rolemi je možné popsat pomocí tzv. diagramu případů užití (angl. use case diagram), které rolím přiřazují způsoby použití systé mu. Vzhled diagramů by měl odpovídat běžným zvyklostem tak, aby byl pro čtenáře srozumitelný. Je například možné se držet standartu UML. Názornost popisu uživatelského rozhraní zvýší vložené snímky obrazovek (angl. screenshot). Jejich zařazení by mělo být maxi málně prostorově úsporné (zvolit vhodné výřezy, uvádět jen ve složitějších případech…). Každý obrázek, diagram, snímek obrazovky, tabulku apod. je třeba opatřit srozumitelným popiskem (umisťuje se pod ob rázek).
Úvod a závěr Úvod by měl čtenáři poskytnout představu co v práci najde a jak je práce strukturovaná. Můžeme jej chápat jako po drobnější rozpracování anotace. V úvodu by měl být zřetelně uvedený seznam námi stanovených cílů projektu, např: » najít efektivní algoritmus a vhodnou datovou strukturu pro určitý problém; » vytvořit knihovnu pro zobrazování prvků hry s využitím nové technologie; » navrhnout a implementovat úspornou komunikaci mezi dvěma programy; » vytvořit prototyp čidla a implementovat software na snímání hodnot apod. Do úvodu můžeme uvést i náš vztah k tématu práce – jak jsme se dostali k problematice, kterou projekt řeší; co od realiza ce projektu očekáváme apod. Závěr patří hodnocení projektu: » zda došlo k naplnění cílů projektu; » proč došlo k případnému nenaplnění cíle projektu; » vymezení finální stavu – kam až jsme dospěli, případně co chy bí;
U každého tématu zvážíme přínosnost a vhodnou míru jejich podrobnosti. Vodítkem nám mohou být klíčová témata. Nad bytečný text odstraníme.
» hlavní úskalí při zpracování projektu a jak se jim v budoucnu vyhnout;
Prvky doplňující text
Časté chyby
Do textu je možné vkládat úryvky zdrojového kódu (angl. snippets). Zařazením úryvku se snažíme čtenáři sdělit nějakou informaci – například použitou datovou strukturu, zajímavý algoritmus, řešení nějakého krajního stavu apod. Zdrojový kód nemusíme přepisovat doslovně – často je vhodné jej zjednodušit. Úryvek by měl být pouze tak dlouhý, aby čtenář „jedním pohle dem“ měl možnost pochopit sdělenou informaci. Dlouhé, někdy dokonce vícestránkové zdrojové kódy do dokumentace nepatří.
» projektu nerozumím (nechal jsem si jej zpracovat někým ji ným) a tedy nemám v práci co sdělit;
Slovní popis můžeme nahradit vhodným diagramem, např: » u rozsáhlejších projektů je vhodné diagramem znázornit archi tekturu systému – tedy rozdělení na moduly, balíčky apod.; » v případě objektového návrhu je vhodné uvést diagram tříd (angl. class diagram) s vyznačením dědičnosti, případně roz hraní; » důležitý postup nebo algoritmus můžeme popsat vývojovým diagramem nebo tzv. diagramem aktivit (angl. activity dia gram); » s popisem datové struktury u databázových aplikací pomůže některá z konvencí diagramu entit a relací (angl. ER dia gram); » pokud mají objekty programu složitější systém stavů a přecho Jak psát dokumentaci k ročníkovému projektu z programování
» další možný rozvoj projektu apod.
» nesrozumitelná struktura textu; » nedostatečně vyjasněná nebo zdůrazněná klíčová témata práce; » nedostatečná informační hodnota práce; » použití odborných termínu, které nejsou vysvětleny; » špatné použití odborných termínů (např. v rozporu se zvyk lostmi); » do práce jsou vloženy příliš dlouhé zdrojové kódy; » celá práce má podobu uživatelské příručky; » příliš mnoho snímků obrazovky; » snímek zobrazuje celou plochu obrazovky a texty jsou neči telné – v takovém případě je vhodné použít výřezu; » v práci jsou převzaté obrázky nebo diagramy a není uveden zdroj; » práce výrazně přesahuje požadovaný rozsah. Není vhodné nazvat kapitolu nadpisem „Samotný text práce“ apod. Na tomto místě se předpokládá více kapitol, jejichž název bude odpovídat obsahu. str. 2
Práce pozbývá na atraktivnosti, pokud obsahuje pouze text bez obrázků, diagramů, snímků obrazovky apod.
1.5. Citace V práci je možné použít obrázky, diagramy, zdrojové kódy nebo úryvky textu cizích autorů. V takové případě je nutné vždy uvést citaci! Týká se to i materiálů stažených z internetu. Všechny citace se uvádí v příloze na konci dokumentu a z textu se na jednotlivé zdroje odkazuje.
Příklad citace knihy příjmení autora, iniciál křestního jména, rok vydání, název, na kladatel, místo vydání, počet stran, ISBN
» poznámky pod čarou, vsuvky, odkazy, citace. V českém prostředí se nejčastěji používá třetí osoba, kdy potla čujeme osobu autora, např: „je možné konstatovat“, „je jisté“, „je třeba říci“, „bylo by myslitelné“, „dá se usoudit“, „bylo zjištěno“ apod. Časté je i použití trpného rodu. Setkat se můžeme i s první osobou množného čísla, kdy se autor ztotožňuje se čtenářem (tzv. autorský plurál), např. „může me se domnívat“, „z toho vyvodíme“. V anglosasky pojatých textech se setkáme i s první osobou jednotného čísla – slouží zejména při formulaci pohnutek v úvo du práce, případně zhodnocení.
Novák, J., Svoboda, S. 2004. Toxikologie živočichů. Orbis. Praha. 260 s. ISBN: 8086261778.
Pro dobrou orientaci v textu, vedle výše zmíněné struktury kapi tol, pomůže i správná volba odstavců. Zlaté pravidlo zní – každý odstavec by měl obsahovat právě jednu informaci! Dlouhé od stavce bývají často zmatečné a je vhodné je rozdělit.
Příklad citace článku
Časté chyby
příjmení autora, iniciál křestního jména, rok vydání, název článku, název časopisu, ročník (číslo), strany od – do
» text se skládá z dlouhých nepřehledných odstavců;
Kosková, L., Hubská, I., Krásná, P. 2002. Diagnostické metody. Český lékař. 56 (3). 130 – 142.
» text je zmatečný, pleteme „páté přes deváté“;
Příklad citace z internetu příjmení autora, iniciály autora, název článku, název zdroje [druh média], datum vydání [citováno dne], dostupné z
Souleimanov, E., Svoboda, K. Čečenská válka a ruská společnost. Středoevropské politické studie [online]. 2006 [cit. 2007-10-02]. Dostupné z .
Odkazy na citace Na začátku citace je možné uvést číslo nebo zkratku v hranatých závorkách pomocí které se pak v textu dokazujeme. [NOV] Novák, J., Svoboda, S. 2004. Toxikologie živočichů. Or bis. Praha. 260 s. ISBN: 8086261778.
1.6. Přílohy Je-li to vhodné, je možné práci doplnit o rejstřík, seznam tabulek, obrázků a ukázek zdrojových kódů. Tyto části ale nejsou povinné.
2. Stylistika odborného textu
» v jednom odstavci mícháme více „témat“; » volba nesprávných nebo nepoužívaných odborných termínů – je vhodné jejich použití zkontrolovat v dostupné literatuře; » studenti si někdy sami „počešťují“ cizí (zejména anglická) slova – je lepší hledat český název, nebo použít původní tvar a zá roveň vysvětlit jeho význam; » autor text pojímá jako vyprávění, používá minulého času na příklad ve spojeních „mým úkolem bylo“, „vybral jsem si“, „za čali jsme vyvíjet“. Častým problémem studentů je použití tzv. slovních berliček – slova která lze vypustit bez změny významu věty – čímž dochází k zpřehlednění textu. Může jít například o slova (záleží na kontextu věty): „tato“, „takto“, „některých“, „nejprve“, „pře devším“, „ovšem“, „zde“, „příliš“, „zejména“ apod. Při zpracování této kapitoly bylo použita práce „Komentovaná antologie vybraných slohových útvarů“, kterou zpracoval Lukáš Průša pro Wichterlovo gymnázium Ostrava: http://www.wigym.cz/nv/wp-content/uploads/docs/opory/stylis tika.pdf, a prezentace Stylistické minimum, zveřejněné na stránkách FEL ČVUT: http://motor.feld.cvut.cz/www/materialy/Y14TED/Y14TED d03_2010n.pdf
Odborné texty musí být především přesné a srozumitelné. Tomu je třeba přizpůsobit volbu jazyka a slohového stylu. Vhodným tréninkem je čtení cizích odborných textů. Slohový styl odborného textu se nejčastěji blíží výkladu, v ně kterých pasážích může jít o popis nebo esej. Autor předkládá čtenáři fakta a pracuje s nimi. Pro odborný styl je typické: » logická stavba, věcnost, objektivita, návaznost; » přesnost, výstižnost, úplnost; » neosobnost, potlačení emocionality a expresivity; » častý výskyt odborných slov, symbolů a zkratek; » jednoduchá stavba věty, větná stavba a slova se často opakují (zejména slova širokého významu – být, mít, dát apod.); » souřadně spojené věty ve významu příčinném, důsledkovém nebo vysvětlovacím; » využití závorek pro méně důležité, doplňující informace; » zdůrazňování pomocí podtržení (již se nepoužívá), kurzívy a tučného textu; » využití odrážek a číslovaných seznamů; » využití tabulek a grafických prvků; Jak psát dokumentaci k ročníkovému projektu z programování
str. 3
3. Formální podoba práce Pro přípravu ročníkové práce lze použít jakýkoli moderní tex tový procesor nebo DTP program, např. Microsoft Word, Open Office Writer / Libre Office Writer, LaTeX, Scribus apod. Zpracování textu velmi usnadní použití stylů.
Formát strany a úprava odstavců Ročníková práce má formát A4. Levý (vnitřní) okraj strany je kvůli vazbě nastaven přibližně na 3 cm, ostatní okraje jsou na staveny přibližně na 2,5 cm. Dokument tiskneme jednostranně. Řádkování je zvoleno jednoduché. Odstavce je možné odlišit mezerou mezi nimi, nebo odsazením prvního řádku odstavce. Práce by měla mít nastaveno záhlaví nebo zápatí s číslem stra ny (s výjimkou první stránky). Do záhlaví nebo zápatí je možné přidat celkový počet stran a název práce. Zarovnávání je vhodné nastavit do bloku a aktivovat dělení slov. Je možné použít dvousloupcovou sazbu.
Písmo Pro dobrou čitelnost textu je vhodné použít patkové písmo (např. Times New Roman, CMU Serif). Důležité části textu mů žeme zvýrazňovat tučným písmem nebo kurzívou. Patkové písmo textu se zpravidla doplňuje bezpatkovým písmem nadpisů (např. Arial, CMU Sans serif). Ale jsou možné i jiné kombinace. Úryvky zdrojových kódů a proměnné v textu sázíme nepropor cionálním písmem (např. Courier New, CMU Typewriter text).
Nadpisy Nadpisy kapitol jsou hlavním nástrojem pro vyznačení struktury textu. Je možné využít dvou nebo tří úrovní nadpisů – tomu by mělo odpovídat způsob jejich číslování (1., 1.1., 1.1.1, atd…). Je možné nadpisy zvýraznit barevně.
Časté chyby » před každým nadpisem kapitoly je odstránkováno a tak je v práci více bílého místa než textu – u kratších prací takové nastavení není vhodné; » nadpisy bez číslování;
správně text (text text) text „text text“ Text: text, text. text text – text 1914–1918 chcete-li
špatně ( text ) „ text “ Text : text , text.text text - text 1914 – 1918 chcete – li
Psaní čísel a matematických výrazů » desetinná část čísla se odděluje od celé části desetinnou čárkou, nikoli tečkou a píše se bez mezer; » kolem desetinné čárky se nepíší mezery » u nejméně pěticiferných čísel se číslo člení do skupin po třech číslicích (oddělují se pevnými mezerami), a to na obou stranách od desetinné čárky, letopočty se nedělí; » u peněžních částek se skupiny číslic mohou oddělovat tečkou; » u matematických výrazů se před a za operátory píší mezery, za unárními operátory se mezera nepíše; » pro mínus se používá speciální znak nebo pomlčka, pro krát křížek nebo zvýšená tečka; » u složitějších matematických výrazů je vhodné použít editor rovnic; » exponenty, indexy, stupně, procenta se píšou bez předchozích mezer. správně
špatně
12 345,678 9 30 000 000 12.000 Kč nebo 12 000 Kč 2 × 5 = 10 nebo 2 · 5 = 10 –2 °C 12m2, (a + b)2; H2SO4 12°, 15,5%
12345. 6789 3000 0000 12000 Kč 2x5=10 nebo 2.5=10 - 2 °C 300 m2, (a + b) 2; H2SO4 12 °, 15,5 %
» nevhodná kombinace písem;
Psaní dat a časových údajů
» chybějící číslování stránek;
Stanovuje norma ČSN ISO 8601.
» nedostatečné okraje pro vazbu; » příliš velké písmo, mezery mezi odstavci nebo řádkování.
» V souvislém textu se den v měsíci i měsíc píší bez „vodící“ nuly, měsíc je možné psát slovy a den, měsíc a rok se oddělují mezerou.
4. Základní typografická pravidla
» Při vyplňování rubrik a v tabulkách je možné psát datum do hromady bez mezer – údaje lze oddělovat spojovníkem nebo tečkou a čísla jsou uvedena dvojmístně.
Psaní mezer, závorek a interpunkčních znamének
» Časové údaje se píšou dvojmístně a oddělují se dvojtečkami bez mezer nebo bez vodící nuly a oddělují se tečkou.
» mezi závorkami a textem uvnitř závorek se mezery nedělají; » mezi uvozovkami a textem uvnitř uvozovek se mezery nedělají; » před čárkou, tečkou nebo dvojtečkou se nedělá mezera, za nimi ano (pokud je znamének více, pak pouze za posledním); » pomlček je několik typů – mezi slovy se používá pomlčka (delší), nikoliv rozdělovník (kratší); » před pomlčku a za pomlčku se píše mezera, pokud se nejedná o rozsah (lze využít slovní vyjádření); » kolem spojovníku se mezera nedělá.
Jak psát dokumentaci k ročníkovému projektu z programování
správně 8. listopadu 2012 nebo 8. 6. 2012 08.11.2012 nebo 2012-11-08 09:45 nebo 9.45
špatně 08.listopadu 2012 08 . 11 . 2012 nebo 2012 - 11 - 08 9 : 45 nebo 09.45
Pro psaní zdrojových kódů neplatí některé výše zmíněné zvyk losti – např. se používají americké uvozovky ("), desetinná tečka v číslech apod.
str. 4
5. Vhodný postup při psaní práce
stranu, zadání, anotaci apod.
» Na práci je vhodné začít pracovat ve chvíli, kdy dospějeme do stavu, kdy „máme o čem psát“. Projekt musí být již v pokročilém stádiu, ale ne nutně finálně hotový.
» Přípravě textu může pomoci dobré nastavení dokumentu v textovém editoru – zejména nastaní stylů pro nadpisy, po pisky obrázků a diagramů, zdrojové kódy, odrážky apod. Vzhled dokumentu se tak přiblíží finální verzi.
» Pokuste se vytvořit počáteční strukturu dokumentu – na pište si témata, která chcete v práci sdělit a rozvrhněte je do kapitol. Znalost struktury je pro proces tvorby důležitá – od začátku víme „co kam psát“.
» V rozpracované fázi je vhodné práci zkonzultovat s vyuču jícím, který může poskytnout zpětnou vazbu jak je srozumi telná struktura textu, nebo poradit ke konkrétním tématům – co chybí, co rozšířit, co zkrátit, co vypustit.
» Na kapitolách nemusíte pracovat v jejich pořadí, ale zpra cováváte nejdříve ty části, ke kterým víte co napsat. Jak bude text přibývat, budou vyplývat i vhodné změny ve struk tuře práce.
» Překlady anotace proberte se svými vyučujícími jazyků.
» Při psaní vás budou asociativně napadat další témata a myš lenky ke zpracování – vše si hned zapisujte – můžete využít komentáře, barevně označený text apod. » V průběhu práce doplňte formální náležitosti – úvodní
Jak psát dokumentaci k ročníkovému projektu z programování
» Před dokončením dokumentu zkontrolujte konečnou struk turu textu, jeho obsah a srozumitelnost; udělejte jazykovou a typografickou korekturu (i s nimi vám může někdo pomoci); vložte obsah (seznam kapitol) – vytvoří automaticky textový procesor; zkontrolujeme stránkování apod… » Dokumentaci vytisknete. Práci svažte vhodnou vazbou.
str. 5
