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

Datum poslední modifikace: 6. 2. 2024



Obecně

Dokumentaci k 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, .pdf (dle nabídky Project Office 365 ), .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. Pro obsahovou náplň odevzdávaných dokumentů použijte šablony, níže v tabulce uvedené, které můžete vhodně upravit a doplnit dle konkrétní situace řešeného problému ( tj. použitého vývojového přístupu, použitého vývojového prostředí, specifika projektového týmu, apod.).

Dokumentace se odevzdává prostřednictvím IS VUT, dle příslušnosti k týmu nebo musí být dle plánovaných termínů dostupná na webových stránkách týmu.

Dokumenty Stran textu (cca) Šablona
Definice problému,
Úvodní studie
2-5 zde
zde
Specifikace požadavků, analýza,
Přezkoumání požadavků
5-10
2-3
zde
zde
Plán projektu 2-5 zde
Plán etapy (implementace) 1-2 zde
Návrh 3-7 zde
Výsledky oponentury 1-2 zde
Konfigurační řízení 2-3 zde
Zdrojové texty programu všechny -
Zpráva o testování, změnové řízení 3-5 zde
Referenční a uživatelská příručka 4-10 zde
Záznamy o schůzkách, protokoly o ukončení etap 2-5
zde
Uzavření projektu, závěrečné zhodnocení
2-5
zde
Seznam rizik s možným dopadem na cenu/čas/kvalitu/rozsah) ve vašem projektu a návrh preventivních opatření. Na každého člena týmu minimálně 5 identifikovaných rizik. Může být součástí dokumentu plánu projektu. Náměty k identifikaci rizik. 6-9
Metriky výsledného produktu - nejméně 10 metrik (např. počet funkcí, počet tříd, počet skriptů, chyb, apod.) 1-2
Sledování a vyhodnocení trvání prací na projektu (plánované/skutečné) *1
3-5
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.). *2


2-3
Logická rámcová matice *3 2-3
* tým (9 členů) si může zvolit jednu ze tří alternativ, který dokument vytvoří.
* tým (10 členů) si zvolí dvě ze tří alternativ, které dokumenty vytvoří.
* tým (11 členů) vytvoří všechny tři uvedené možnosti.

Formální náležitosti dokumentů

Každý dokument odevzdávaný v rámci projektu MPR 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í.

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 (Project Office 365, 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ů

Management projektů

<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, aby 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.1 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 potřebných 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říklad dokumentu

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, k činnostem přiřazené role, osoby, náklady. Musí být vytvořený v MS Project.
  5. Způsob předání - jak bude výsledný 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, náklady.
  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é moduly, pro každý budou nejméně dva testovací případy.

    Software testing - typy testů Automatizace testů

    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
    Možný obsah na dokumentaci některých fází najdete zde:
    Metodika OO vývoje aplikací

    Odevzdávání výsledného produktu

    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, případně odevzdána dle pokynů vedoucího asistenta (např. v dokumentovém skladu).


    Management projektů