
Posudok k dokumentácii tímu č.11

Čo v dokumentácii chýba:

Úvod: chýbajú ciele projektu, predstavenie riešiteľského kolektívu;
Špecifikácia: chýba špecifikácia údajov (napr. ERD), kontext systému (DFD), ako aj špecifikácia správania systému;
Zápisnice zo stretnutí: chýba čas stretnutí (dátum je nepostačujúci), ako téma stretnutia je vždy uvedené: "niečo" – zrejme sa pozabudlo na kontrolu zápisníc pred dokončením;
Ďalej chýba rozdelenie úloh členov riešiteľského tímu a takisto aj ohraničenia.

Nedostatky v tom, čo nechýba:

Úvod:
Úvod je veľmi stručný, neobsahuje žiadne uvedenie do problematiky.

Analýza:
Analýza je (oproti špecifikácii) až prehnane rozsiahla, venuje sa v nej veľmi veľa priestoru už existujúcim riešeniam, ktoré sú pre JSI do istej miery nepoužiteľné, ba čo viac, na konci sa konštatuje, že "Ďalej sa ním zapodievať nebudeme.".
Časť 2.5.5 do analýzy problému nepatrí.

Špecifikácia:
Celkovo je časť špecifikácie požiadaviek na veľmi slabej úrovni, obsahuje v podstate iba špecifikáciu funkcií systému.
Obsah posledných odstavcov časti "Došpecifikovanie požiadaviek" nepatrí do špecifikácie požiadaviek. Okrem toho, vysvetlenie, prečo bude vynechaná "databázová" časť ("Táto úloha sa nám zdá byť hodnotnejšia, nakoľko databázovými systémami sme sa zaoberali v iných ročníkoch a na iných predmetoch") je scestné, pretože práve preto by mal tím tieto skúsenosti preukázať v projekte. Veď projekty by mali byť prezentáciou (ukážkou) schopností, ktoré boli nadobudnuté počas štúdia.

Hrubý návrh:
V hrubom návrhu sa tím venuje iba porovnávaniu programov a testovaniu funkčnosti, čo je dosť málo. Niektoré časti by mali byť skôr v špecifikácii (práve v chýbajúcich častiach špecifikácie).
Je zaujímavé, že sa tím rozhodol proti jednoznačnej vôli odberateľov (resp. budúcich používateľov), ktorými sú cvičiaci predmetu SOJ.
Takisto je zaujímavé, že si tím zvolil ako cieľovú platformu OS Linux, pretože je málo pravdepodobné, že v blízkej budúcnosti bude tento systém využívaný práve budúcimi užívateľmi systému. Zaujímavý je aj dôvod, prečo sa tím rozhodol pre takéto riešenie: "... a tiež z dôvodu, že väčšina tímu, ktorá sa bude podieľať na implementácii má výborné znalosti v programovaní na tejto platforme.". Prečo je to zaujímavý dôvod? Lebo sa nestáva často, aby si riešiteľský tím diktoval cieľovú platformu. To by sa ľahko mohlo stať, že odberateľ (budúci používateľ) bude nespokojný a produkt odmietne.
Čo sa týka testovania, je dôležité to, ako kvalitne je spravený emulátor MS DOS v prostredí OS Linux, pretože študent bude svoje zadania implementovať a ladiť hlavne v prostredí MS DOS a nebude rátať so žiadnymi špeciálnymi vlastnosťami OS Linux a jeho VDM (Virtual DOS Machine).

Ponuka:
Ponuka tímu je veľmi stručná. Je potrebné poznamenať, že "Počítačové systémy a siete" nie je odbor, ale zameranie odboru. Odbor je Informatika.

Postrehy k niektorým častiam (výrokom):

Štruktúra dokumentácie sa nestotožňuje s praxou overenými štruktúrami (postupnosť: analýza problému; špecifikácia požiadaviek – funkcie, údaje a správanie; ...). To síce nie je veľký nedostatok, ale podstatné je to, že dokumentácia neobsahuje spomenuté chýbajúce časti.

Drobný postreh k časti 2.3: testovanie funkčnosti je dôležitá fáza, no štatisticky určite nezaberá 80% z celkového vývojového času. Zrejme je myslený čas od začiatku implementácie.
V časti 2.5 je napísané, že "Preto je len prirodzené, že niektorí takýto študenti sa snažia vyhnúť "nezaujímavej" práci ...". Dúfame, že to nemá byť ospravedlnenie týchto študentov, ale len akési "pochopenie" ich pohŕdania programovaním jednoduchších úloh. Každopádne má zmysel zaoberať sa aj týmto, pretože títo študenti sa zrejme mylne domnievajú, že dobrý programátor sa zaoberá výhradne zložitými úlohami. A okrem toho, je možnosť dohodnutia semestrálneho zadania, ktoré je komplexnejšie a ktoré nahradí viac jednoduchých úloh. Tu je na mieste otázka, či to nesúvisí s motiváciou študentov.
K časti 2.5.3 je vhodné poznamenať, že ak sa porovnávaním atribútov zistí, že zadania sú podobné (nie rovnaké – vtedy je to jasné), je to len upozornenie, že ich treba podrobiť inteligentnému testu. V žiadnom prípade by sa takéto výsledky nemali považovať za smerodajné pri hodnotení.

Formálna stránka (gramatické chyby a slovosled):

V množnom čísle sa píše dlhé mäkké 'í', napríklad v slovách: "konštrukcii", "z technik", "ktorý".
Viackrát sa v dokumentácii stáva, že v slovách chýba písmeno: "z funkčný jednotiek", "tomuto problém", "zoberá".
Chýbajú čiarky ako oddeľovače: "je otázne či".
Slová "nieje" a "niesú" sa píšu oddelene.
Používajú sa nespisovné slová: "pomenenie", "poprepisovať", "parser".

Dokumentácia obsahuje aj ďalšie typy chýb, napríklad chybné stupňovanie niektorých prídavných mien ("najuniverzálnejší"), neukončenie vety bodkou, opakovanie slov, používanie nesprávnych tvarov slov ("štandartne") a podobne. Uvedené konkrétne gramatické chyby sú vybraté ako ukážky.

Dokumentácia sa ťažko číta (aj kvôli častým gramatickým a štylistickým chybám). Niektoré vety v dokumentácii sú "umelo" vytvorené, predlžované ("..., alebo ďalšiu doplniť, bolo by potrebné podrobne zbytočne naštudovať funkciu celého modulu") a štylisticky nesprávne (zlý slovosled vo vetách), čo má potom za následok, že takéto vety je potrebné prečítať viackrát, aby bol pochopený ich význam.
Celkovo na nás dokumentácia pôsobí, akoby bola "šitá horúcou ihlou", lepšie povedané, akoby bola robená v časovej tiesni. (V časti Prílohy sa napríklad zabudlo na text s označením "Toto možno do záveru".)

Záver:

V tomto posudku sme sa venovali hlavne nedostatkom, pretože v procese vylepšovania dokumentácie je treba odstraňovať iba nedostatky. A práve vylepšenie hodnotenej dokumentácie je hlavným cieľom tohto posudku.

Pripúšťame, že niektoré uvedené výhrady nemusia byť v konečnom dôsledku opodstatnené, pretože mohla vzniknúť situácia, kedy sme presne neporozumeli, čo mal autor tej-ktorej časti na mysli. Každopádne však veríme, že odstránenie spomenutých nedostatkov povedie k zvýšeniu ako obsahovej, tak aj formálnej úrovne dokumentácie.

Na záver treba poznamenať, že to, čo nebolo označené ako nedostatok, je chápané pozitívne. A aj keď sa s niektorými vecami nestotožňujeme, akceptujeme ich ako iný pohľad na vec, teda ako iné (ale nie zlé) riešenie.
Medzi výraznejšie pozitíva patrí (so spomenutými výhradami) slušne urobená analýza problému, zaujímavá myšlienka zhodnotenia efektívnosti programu. Zaujímavým riešením je aj napriek istým úskaliam emulácia MS DOS v prostredí OS Linux. Dobre spravená je aj časť zaoberajúca sa podobnosťou programov.

Poznámky: