Pravidla pro formát, obsah a odevzdávání dokumentů

Datum poslední modifikace: 1.2.2006



Obecně

Dokumentaci projektu můžete psát v téměř libovolném systému, či editoru dosažitelném v prostředí CVT

Doporučeny jsou Microsoft Word, HTML, .mpp (MS Project), prj (Rational Rose). Důležitá je správnost a čitelnost textu. K tomu přispívá zejména gramatická správnost, rozumná vyjadřovací schopnost a přehledná struktura dokumentu. Počet stránek v tabulce uvedený je přibližný a nepočítá se do něj titulní stránka.

Dokumentace se odevzdává prostřednictvím IS FIT, dle příslušnosti k týmu.

Dokumenty  Stran textu (cca)
Definice problému, Úvodní studie 2-5
Specifikace požadavků, analýza 5-10
Plán projektu 2-5
Plán etapy 1-2
Návrh 3-7
Výsledky oponentury 1-2
Konfigurační řízení 2-3
Zdrojové texty programu všechny
Zpráva o testování 3-5
Referenční a uživatelská příručka 4-10
Záznamy o schůzkách, protokoly o ukončení etap 2-5
Uzavření projektu, závěrečné zhodnocení
2-5
Sledování a vyhodnocení trvání prací na projektu (plánované/skutečné)* 3-5
Metriky produktu - nejméně 10 metrik (např. počet funkcí, počet tříd, počet skriptů, chyb, apod.)*

Zpracujte data o příčinách chyb ve vašem projektu. Použijte Paretovu analýzu. Výsledky prezentujte pomocí Paretových digramů (soft. podp. např. zde). Zvolte jednotné náklady na odstranění zjištěných závad (100 Kč/hod.). *

* pouze pro týmy, které mají 8 - 10 členů

Formální náležitosti dokumentů

Každý dokument odevzdávaný v rámci projektu RPS bude obsahovat následující části (v uvedeném pořadí):

Titulní stránka

Obsah (pro dokumenty delší jak 2 strany).

Úvod s uvedením účelu a přehledem zbytku dokumentu. Zde je vhodné také uvést tabulku zkratek a odkazy na zdroje informací k řešenému problému.

Text dokumentu členěný na číslované oddíly.

Je velmi vhodné, aby všechny dokumenty jednoho týmu měly stejnou (nebo podobnou) grafickou úpravu - titulní stránka, použité typy písma, systém očíslování.
Můžete použít šablony z
Metodiky OO vývoje aplikací

Titulní stránka

Vzhledově bude stejná pro všechny dokumenty. Obsahuje identifikační údaje. Název týmu je dle vaší vlastní volby na začátku semestru, Název projektu podle zadání, Název dokumentu, např. "Dokument specifikace požadavků".

Pokud bude dokument produktem jiného systému (MS Project, Rational Rose), je nutné dbát na to, aby tyto informace byly na patřičných místech zaznamenány.

Vzor obsahu titulní stránky dokumentu:

Fakulta informačních technologií
Ústav informačních systémů

Řízení projektů systémů založených na počítačích

<Název projektu>

<Název dokumentu>

<Název týmu>

<Autoři dokumentu>

<Datum>

Jako autoři budou uvedeni jen ti členové týmu, kteří se na přípravě dokumentu aktivně podíleli; za jménem člena, který je za dokument zodpovědný jako "manažer fáze", bude uvedena příslušná indikace.

Obsah

Standardní obsah dokumentu; úroveň detailu (zda budou uvedeny sekce N nebo i N.N nebo dokonce N.N.N) zvolte vhodně podle délky a složitosti dokumentu. Pokud dokument obsahuje množství obrázků a/nebo tabulek, je vhodné vytvořit a za obsah připojit také seznam těchto elementů.

Úvod

Stručný a jasný přehled, čeho se dokument týká a jaké má části; nutnou součástí každého dokumentu. Stačí dva, maximálně tři odstavce; mají být napsány tak, abych nemusel čtenář už dál číst a přesto měl přehled o celém dokumentu.

Pokud se jedná o technický dokument, hemžící se zkratkami a akronymy, je nutné uvést zde i vysvětlující tabulku (zkratka, plný text). Může být vhodné zde také uvést odkazy na další dokumentaci (např. pro návrhové dokumenty, odkaz na specifikaci požadavků, literaturu o používaných metodách apod.)

Text

Čleňte jej do očíslovaných sekcí (např. 1. Úvod) a podsekcí (např. 1.2 Použité nástroje) - číslování usnadňuje orientaci a odkazy. Taktéž číslujte obrázky, diagramy a tabulky, podle vhodného systému konzistentně uplatňovaného. Používejte jednotný font.

Soustřeďte se především na obsah. Nerozlévejte se do epické šíře, pište stručně a jasně, ale s uvedením všech informací.

Rejstřík

Pokud se jedná o velmi dlouhý dokument a/nebo členitý dokument, je dobré mít na konci rejstřík (neboli index), jako je v každé dobré technické knize; např. se může hodit pro detailní návrh nebo rozsáhlou specifikaci požadavků.

Obsah jednotlivých dokumentů - rámcově

Definice problému, úvodní studie

Viz příkladový dokument

Plán projektu

  1. Úvod
  2. Použitý model životního cyklu.
  3. Složení a role týmu - kdo je za co globálně zodpovědný -- hlavní manažer, vedoucí pro jednotlivé etapy.
  4. Harmonogram - tabulka s uvedením etap a jejich významných částí, dob jejich trvání, milníky (finální verze dokumentů apod.) s termíny, datumy oponentur.
  5. Způsob předání - jak bude produkt předveden a předán zákazníkovi.

Plán etapy

  1. Úvod
  2. Složení a role týmu - vedoucí etapy, kdo je konkrétně zodpovědný za jaký úkol.
  3. Harmonogram - tabulka s uvedením úkolů, odpovědností za úkoly, dob jejich trvání, termíny.
  4. Způsob uzavření etapy - jak bude stanoven přechod na další etapu.

Specifikace požadavků

Podrobný popis struktury dokumentu viz výtah z IEEE standardu.

Bude obsahovat např. model jednání, diagram tříd. Musí být posouzen a schválen uživatelem (bude kontrolováno). Nezapomeňte si naplánovat schválení tohoto dokumentu.

Detailní návrh

podklad pro oponenturu

  1. Úvod
  • Účel a hlavní funkce systému
    1. Přehled modulů, z nichž se program bude skládat (pro každý modul/ subsystém jedna podkapitola shrnující jeho účel).
    2. Popisy modulů, např. ve formě důkladně okomentovaného příslušného souboru. Pro každý modul:
    1. Datové a interní konfigurační soubory/tabulky

    Záznam nálezů oponentury

    Může mít např. následující formát:

    Nález oponentury

    Tým:

    Předmět:

    Datum:

    Účastníci:

    Seznam nálezů:

    ..

    ..

    ..

    Opravy provede:

    Celkové zhodnocení:

    Záznam nálezů

    Plán pro konfigurační řízení

    1. Úvod
    2. Rozdělení kompetencí členů týmu (kdo co programuje) a jméno manažera fáze.
    3. Popis vývojové platformy.
    4. Jaké bude používáno softwarové vybavení (překladače editory, správa projektu, správa verzí, built nástroje), způsob zálohování.
    5. Mechanizmy pro zajištění vzájemné komunikace aktuálních verzí, vzájemného vyloučení při přístupu k r/w kopiím, kde a kdy se bude systém sestavovat a jakým způsobem budou k dispozici kompletní zdrojové texty.
    6. Mechanizmus zpracování požadavků na změny.
    7. Popis štábní kultury používané pro zdrojové texty --- záhlaví zdrojových souborů, popis typů/proměnných/funkcí, konvence jmen, způsob odsazování, ..

    Zpráva o testování

    Požadovaná dokumentace nebude úplným plánem testování, cílem je pokrýt nejpodstatnější informace pro specifikaci a výsledky testů. Provedené testy budou testovat nejméně dva vybrané programy, pro každý budou nejméně dva testovací případy.

    1. Úvod ( kterého sw se testování týká, odkazy na specifikaci a design dokument.)
    2. Postup testování
    1. Specifikace testovacích případů

    Pro každý testovací případ bude uvedeno:

    Uživatelská příručka

    1. Úvod
    1. Instalace programu
    1. Základy práce s programem
    1. Referenční příručka
    Konkrétní obsah na dokumentaci některých fází a šablony dokumentů najdete na:
    Metodika OO vývoje aplikací


    Odevzdávání programu

    Program se odevzdává ve třech fázích:

    !!! Nezapomeňte uvést do plánu projektu !!!

    Upozornění: Instalace je nutnou součástí projektu. Budou také dodány zdrojové texty, které musí obsahovat README soubor s popisem struktury a INSTALL s popisem instalace. Veškerá definitivní dokumentace projektu, včetně vytvořené aplikace (zdrojové texty) bude vhodně strukturována do adresářů a odevzdána na CD. 


    Řízení projektů systémů založených na počítačích