Katedra počítačov a
informatiky, Fakulta elektrotechniky a informatiky, TU Košice
Štandard KPI 10, verzia 4
Dokumentácia pre programové prostriedky
Obsah:
1 Štruktúra dokumentácie.. 1
2 Dokumenty pre vypracovanie programov........ 1
3 Dokumenty pre spracovanie a údržbu
programov........ 2
3.1 Obsah dokumentov 2
3.2 Príklad osnovy Systémovej príručky........ 2
3.3 Doporučenia pre konštrukciu
programov... 3
3.4 Tvar zdrojových textov programu...... 4
4 Dokumenty pre používanie programov........ 4
4.1 Rozsah dokumentov 4
4.2 Používateľská príručka 5
4.3 Príručka systémového programátora a
operátora...... 5
4.4 Príklad osnovy Používateľskej príručky........ 5
5 Dokumenty pre riadenie projektov.......... 6
5.1 Organizačné zabezpečenie prípravy a
vlastnej prevádzky programového systému........ 7
6 Pokyny na popis médií....... 8
7 Titulné strany................ 8
Dokumenty sa delia na 4 základné skupiny:
1/ dokumenty pre vypracovanie programov,
2/ dokumenty pre spracovanie a údržbu programov,
3/ dokumenty pre používanie programov,
4/ dokumenty pre riadenie projektov.
Dokumenty pre vypracovanie programov bližšie definujú požiadavky na realizáciu daného programového vybavenia, popisujú účel a oblasť použitia riešeného programu, definujú prípadne požiadavky na programovú dokumentáciu a východzie údaje pre postup spracovania. V praxi tento druh dokumentov má značný význam a ich názov nemusí byť jednotný. Prvotné dokumenty obyčajne sú: Štúdia, Technické zadanie, Technicko-ekonomický rozbor a pod., ktoré definujú predpokladané ciele úlohy (odpoveď na otázku ČO) s prihliadnutím na časové okolnosti riešenia úlohy (odpoveď na otázku DO KEDY) a na finančné nároky úlohy napr. tiež s výpočtom návratnosti vynaložených prostriedkov (odpoveď na otázku ZA ČO). Na túto dokumentáciu naväzuje projektové spracovanie úlohy a jej vlastná realizácia. Dokumenty predstavujú jednotlivé fázy riešenia úlohy, ktoré sú sprevádzané oponentnými konaniami s výsledkom súhlasu alebo nesúhlasu pokračovania v riešení. V školských podmienkach je venovaná pozornosť projektovému spracovaniu návrhu informačných systémov a počítačových sietí, viď [5, 6].
Pri semestrálnych projektoch (SP), projektoch realizovaných v rámci daných predmetov alebo pri riešení diplomových prác (DP) dokument pre vypracovanie programov má stručný charakter a obyčajne obsahuje:
- názov zadania, prípadne došpecifikácie zadania úlohy,
- predpokladané podmienky riešenia,
- náväznosti na iné úlohy,
- rozdelenie práce pri skupinových úlohách,
- -.prípadne iné okolnosti riešenia.
Dokumenty pre spracovanie a údržbu programov sú v školských podmienkach reprezentované Systémovou príručkou a výpismi zdrojových textov.
Systémová príručka predstavuje dokumentáciu, ktorá popisuje podstatu navrhovaného riešenia, analýzu riešenia, jeho teoretické spracovanie, vlastnú realizáciu a spôsob prekladu. Dokument je určený tiež pre spracovanie a údržbu vytvorených programov. Dokument musí byť natoľko obsažný, aby na jeho základe aj novo zainteresovaní pracovníci mali byť schopní v programovom produkte robiť ďalšie úpravy, vývoj, resp. odstraňovať chyby a pod.
Tvar dokumentácie je daný bližšie druhom realizovaného programového produktu. Pre niektoré programovacie technológie sú vypracované ďalšie postupy, viď [2] „Doplnok k programovej dokumentácii – použitie štruktúrovaného návrhu“ alebo [3] „Doplnok k programovej dokumentácii – použitie objektového návrhu“. Špecifické prípady je potrebné odkonzultovať s príslušným vyučujúcim, ktorý definoval danú úlohu.
Prílohou k Systémovej príručke sú zdrojové texty, ktoré bezprostredne naväzujú na systémovú príručku. Zdrojové texty sú súčasťou “Systémovej príručky“, viď kap 3.3. U DP obsah systémovej príručky obyčajne tvorí súčasť textovej časti DP.
Systémová príručka má svoju titulnú stranu (pokiaľ nie je súčasťou textovej správu DP), ktorej forma je uvedená na konci tohoto dokumentu, viď kap.7.
Niektoré časti systémovej príručky môžu byť generované použitím prostriedkov CASE (počítačová podpora tvorby programových prostriedkov).
Titulná strana podľa kap. 7.
Obsah
- Obsah uviesť s použitím očíslovaných strán a označením kapitol desatinným triedením.
1. Funkcia programu
- Krátky popis funkcie navrhovaného programu.
2. Analýza riešenia
- Analýza riešeného problému včítane teoretického rozboru, porovnanie koncepcii možných riešení, zdôvodnenie zvoleného postupu riešenia a pod.
3. Popis programu
- Maximálne využívať formálne a grafické prostriedky podľa použitej metodológie návrhu.
- Je potrebné urobiť odvolávky na zdrojové texty uvedené v prílohách dokumentácie. Popis častí podprogramov môže byť prebraný z komentárov uvedených v zdrojových textov programov. Hlavné komentáre (celoriadkové) musia odpovedať textovému popisu hrubého algoritmu riešenia.
3.1 Popis riešenia
- Uviesť teoretický základ resp koncepciu riešenia, použité vzťahy a pod. s odvolaním sa na literatúru uvedenú v záverečnej kapitole
3.2 Popis algoritmov a údajových štruktúr, globálnych premenných
- Popis algoritmov uviesť s použitím vhodných formálnych prostriedkov (vývojový diagram, verbálny popis atď.).podľa použitej metodológie návrhu.
- Popis návrhu dialógu s používateľom.
3.3 Popis modulov a podprogramov
- U podprogramov uviesť funkciu, popis vstupných a výstupných parametrov, globálne premenné, ktoré používa, uviesť popis algoritmu. Znázorniť v grafickej forme spôsob vnorenia volaní podprogramov.
3.4 Popis vstupných a výstupných súborov (pokiaľ existujú)
- Popis charakter vstupu, organizáciu a pokyny pre predprípravu vstupných údajov.
4. Preklad programu
4.1 Zoznam zdrojových textov
- Zoznam s odvolaním sa na prílohy.
4.2 Požiadavky na technické prostriedky pri preklade
- Typ potrebného počítača, potrebná veľkosť operačnej pamäte, diskový priestor, prídavné zariadenia atď.
4.3 Požiadavky na programové prostriedky pri preklade
- Operačný systém, typ prekladača a spojovacieho programu atď.
4.4 Vlastný preklad
- Popis príkazových súborov a pod., popis nastavenia, konfigurácie prostredia, v ktorom bol program vyvíjaný.
5. Náväznosť na iné programové produkty
- Napr. program môže využívať programový systém GKS, OpenGL atď.
6. Zhodnotenie riešenia
- Čo je nedopracované, možnosti ďalšieho vývoja, obmedzenia riešenia, existujúce okolnosti riešenia atď.
7. Zoznam použitej literatúry
- Podľa príslušnej STN normy, uviesť aj zdroje z INTERNETu. U citácií z INTERNETu uviesť autora dokumentu (ak je známy), názov dokumentu, jeho WWW adresu a dátum, kedy dokument bol získaný.
8. Zoznam príloh (prílohy obsahujú výpisy zdrojových textov programov)
1. Po spustení programu má sa zobraziť úvodná obrazovka programu, ktorá obsahuje: Názov programu, meno autora, meno vyučujúceho (u DP meno vedúceho a konzultanta-ov), dátum vytvorenia, názov katedry, charakter úlohy (napr. semestrálny projekt, diplomová práca, názov predmetu a pod.).
2. Nevratné funkcie (mazanie, prepis obrazovky, ukončenie programu atď.) programovať s odsúhlasením používateľa.
3. Ovládanie programu, resp. komunikácia s používateľom, musí byť realizovaná v zmysle používaných zvyklostí a daných pravidiel.
Zdrojový text programu tvorí súhrn modulov zdrojových textov, z ktorých je program vytvorený. Textovú správu (popis) k zdrojovým textom predstavuje Systémová príručka. Rozdelenie celého programového celku do jednotlivých súborov a na moduly robí programátor na základe funkčnej štruktúry programu, požiadaviek prekladu, zvláštnosti generovania programu a iných faktorov. Pri tvorbe zdrojových textov je potrebné dodržať zásady:
Text každého súboru zdrojového textu programu obsahuje časti:
1. Na začiatku textu v tvare komentára je umiestnená tzv. “Hlavička programu“, ktorá obsahuje: názov programu, meno autora, meno vyučujúceho (u DP vedúceho a konzultanta-tov), charakter úlohy (DP, semestrálny projekt atď.), dátum, č. verzie programu a prípadný popis úprav s uvedením dátumu a mena, kto vykonával úpravy.
2. Za “Hlavičkou programu“ v tvare komentára, resp. na začiatku každého modulu, podprogramu a pod. všeobecný popis, v ktorom sa uvádzajú: funkcia, prípadné vstupné a výstupné parametre; použité vonkajšie údajové štruktúry; použité vonkajšie moduly a spôsob interakcie s nimi a pod.
3. Príkazovú časť, v ktorej je uvedený zdrojový text programu spolu s komentármi. Komentáre musia byť v súlade s kapitolou Popis programu (vývojovým diagramom, blokovou schémou prípadne iným popisom algoritmu). Systémovej príručky
4. Podprogramy, resp triedy, metódy apod., komentovať: funkcia, popis vstupných a výstupných parametrov. Časti komentárov môžu byť identické s popismi v Systémovej príručke.
5. Algoritmicky nenadväzujúce časti programov oddeľovať celoriadkovým komentárom zo znakov pomlčka resp. rovnítko.
Dokumenty určené pre používanie programov sú určené používateľom programu. Títo nemajú k dispozícii systémovú príručku ani zdrojové texty programu. K dokumentom prislúchajú aj inštalačné média, na ktorých v reálnej praxi sú obyčajne len binárne tvary programov. Dokumenty môžu pozostávať z viacerých častí:
1. Príručka požívateľa,
2. Príručka systémového programátora a operátora,
3. Popis jazyka,
4. Učebnica pre používateľov programu,
5. Popis používateľskej knižnice podprogramov,
6. Súpis príkazov programu a chybových hlásení,
7. atď.
U rozsiahlych programových systémov to môžu byť až tisícky strán dokumentácie. Často je k dispozícii aj v elektronickej podobe. V školských podmienkach vo väčšine prípadov vystačujeme s Požívateľskou príručkou, ktorá obsahuje informácie pre inštaláciu aj používanie programu. Definitívnu skladbu dokumentov pre používanie programu určuje vyučujúci (u DP vedúci alebo konzultant-i). U DP tieto dokumentácie sú obsahom príloh. Hlavnými dokumentmi sú:
Dokument spravidla obsahuje:
1. Popis, čo daný program vykonáva, oblasti použitia, charakteristika riešených úloh prostredníctvom programu, mená autorov, údaje o dodávateľovi, licenčné podmienky a pod., prehľad o dokumentácii k programu.
2. Použitie programu. Popis jednotlivých funkcií a podfunkcií s využitím napr. "hardcopy obrazovky". Popis dialógu s používateľom. Popis použitých metód (napr. numerických a pod.).
3. Popis vstupných a výstupných súborov (pokiaľ existujú), prípadne popis pracovných súborov, formáty súborov atď.
4. Obmedzenia programu.
5. Chybové hlásenia:
- chybové hlásenia vlastné pre daný aplikačný program,
- chybové hlásenia súvisiace s OS, resp. inými náväznými programami.
6. Príklady použitia programu.
7. Demo verzia.
Dokument spravidla obsahuje:
1. Popis, čo daný program vykonáva, oblasti použitia, mená autorov, údaje o dodávateľovi, licenčné podmienky a pod., prehľad o dokumentácii k programu.
2. Súpis obsahu dodávky. Predpokladom je, že je k dispozícii zhotovený program v binárnej forme s inštalačnými podporami. Je potrebné uviesť počet diskiet so zoznamom súborov, ktoré obsahuje inštalačná disketa.
3. Požiadavky na technické a programové prostriedky. (typ počítača, požadovaná veľkosť operačnej pamäte, potrebný diskový priestor, prídavné zariadenia atď., operačný systém, obslužné programy, knižnice atď.).
4. Popis štruktúry programu. Uviesť údaje o moduloch programu a ich spolupráci pri aktivácii programu a taktiež o spoluprácu s inými programami.
5. Vlastná inštalácia. Rozpísať po jednotlivých krokoch aj s očakávanými dobrými a chybovými odozvami.
6. Popis správ pre systémového programátora. Uviesť texty správ, ktoré sa vypisujú počas činnosti programu, príčiny týchto správ, popis činnosti, ktoré je potrebné po týchto správach vykonať.
Príklad osnovy Používateľskej príručky, ktorá obsahuje informácie aj pre systémového programátora:
Titulná strana podľa kap. 7.
Obsah
- S použitím očíslovaných strán a použitím desatinného triedenia.
1. Funkcia programu
- Popis, čo daný program vykonáva, oblasti použitia, charakteristika riešených úloh prostredníctvom programu, mená autorov, údaje o dodávateľovi, licenčné podmienky a pod., prehľad o dokumentácii k programu.
2. Súpis obsahu dodávky
- Predpokladom je, že je k dispozícii zhotovený program v binárnej forme s inštalačnými podporami. Potrebné uviesť:
· počet médií so zoznamom súborov, ktoré obsahuje inštalačné médium;
· zoznam dokumentácie (Používateľská príručka, atď.).
3. Inštalácia programu
3.1 Požiadavky na technické prostriedky
- Typ počítača, požadovaná veľkosť operačnej pamäte, potrebný diskový priestor, prídavné zariadenia atď.
3.2 Požiadavky na programové prostriedky
- Operačný systém, obslužné programy, knižnice atď.
3.3 Vlastná inštalácia
3.4 Popis štruktúry programu.
- Uviesť údaje o moduloch programu a ich spolupráci pri aktivácii programu a taktiež o spoluprácu s inými programami. Po jednotlivých krokoch rozpísať postup aj s očakávanými dobrými a chybovými odozvami.
3.5 Popis správ pre systémového programátora
- Uviesť texty správ, ktoré sa vypisujú počas činnosti programu, príčiny týchto správ, popis programu činnosti, ktoré je potrebné po týchto správach vykonať.
4. Použitie programu
4.1 Popis dialógu s používateľom,
- Napr. pomocou stromu dialógu.
4.2 ........
- Popis jednotlivých funkcií a podfunkcií programu (nie v zmysle programátorských podfunkcii), s využitím napr. "hardcopy obrazovky.
5. Popis vstupných, výstupných súborov a pracovných súborov
- Napr. formáty súborov, atď.
6. Obmedzenia programu
7. Chybové hlásenia
- Chybové hlásenia vlastné pre daný aplikačný prgram.
- Chybové hlásenia súvisiace s OS, štandard. p.p.,...).
8. Príklad použitia
9. Popis demo-verzie
Projektové riadenie je plánovací a riadiaci proces, ktorý pri jednoznačnej zodpovednosti definuje jednotlivé dielčie úlohy, ich náväznosti, sleduje ekonomické a časové súvislosti. Výrazným prvkom je tendencia optimalizácie riešenia napr. z hľadiska časového.
Dielčou časťou tejto problematiky je organizačné zabezpečenie prípravy a vlastnej prevádzky programového systému. Najväčší význam má táto problematika u realizácii počítačového spracovania informácií – informačných systémoch, kde nezvládnutie tejto problematiky má časté následky v neúspechu realizácie celého informačného systému. Z tohoto dôvodu pri DP orientovaných na realizáciu informačných systémov je dokument „Organizačné zabezpečenie prípravy a vlastnej prevádzky programového systému“ povinný, aj keď niektoré podkladové informácie do dokumentu budú mať odhadový charakter.
Dokument je určený predovšetkým pre riadiacich pracovníkov a vlastný personál, ktorý bude programový systém (napr. informačný systém využívať). Dokument pozostáva z nasledovných častí:
- Krátky a výstižný text popisujúci výhody navrhovaného systému v porovnaní s existujúcim stavom Určené predovšetkým pre riadiacich pracovníkov.
-
- Krátky text popisujúci základné funkcie navrhovaného systému. Určené predovšetkým pre riadiacich pracovníkov.
3. Organizačné zabezpečenie prípravy prevádzky systému
3.1 Organizačné zabezpečenie riešenia zo strany používateľov systému
- Definovanie konkrétnych úloh so zodpovedným pracovníkom a termínom plnenia.
- Definovanie organizačného zabezpečenia prevádzky systému (zodpovední riadiaci a výkonní pracovníci – používatelia systému) a definovanie pracovných povinností pre výkonných a riadiacich pracovníkov.
- Definovanie prístupových práv v zmysle projektu riešenia s aplikáciou na konkrétnych pracovníkov.
- Konzultácie riešiteľov s budúcimi používateľmi.
- Zabezpečenie účasti zainteresovaných pracovníkov na prenose údajov do systému.
- Zabezpečenie účasti zainteresovaných pracovníkov na zaškolení.
3.2 Organizačné zabezpečenie riešenia zo strany technickej prevádzky systému
- Príprava technického zabezpečenia chodu systému.
- Zabezpečenie bezpečnosti prevádzky systému (odolnosť voči poruchám a zotavenie, zálohovanie a archivácia).
- Riešenia počiatočného naplnenie systému údajmi - prevod a aktualizácia báz údajov.
- Prevádzkové skúšky systému.
- Vypracovanie používateľskej dokumentácie.
- Realizácia organizačného zabezpečenia prevádzky.
- Zaškolenie pracovníkov.
- Spustenie systému do skušobnej prevádzky.
- Spustenie systému do rutinnej prevádzky.
4. Organizačné zabezpečenie vlastnej prevádzky systému
4.1 Organizačné zabezpečenie vlastnej prevádzky systému
- Úprava pracovných náplní výkonných pracovníkov.
- Úprava pracovných náplní riadiacich pracovníkov.
4.2 Organizačné zabezpečenie vlastnej prevádzky zo strany technickej prevádzky systému
- Úprava pracovných náplní výkonných pracovníkov v zmysle úlohy.
- Úprava pracovných náplní riadiacich pracovníkov v zmysle úlohy.
5. Harmonogram riešenia
- Názov úlohy, termín začiatku riešenia, termín ukončenia riešenia, náväznosť na iné úlohy (použitie Ganttovho diagramu a pod.).
Média (disketa(y), resp. CD disky) ako prílohy musia obsahovať textové dokumenty vo forme príslušných súborov vrátane obrázkov a ďalších produktov počítačového spracovania (zdrojové texty, spustiteľné programy, výkresy a ostatné dokumenty.). Štítok média musí obsahovať:
- názov katedry (pracoviska),
- charakter produktu (Semestrálny projekt, Diplomová práca, názov predmetu a pod.),
- prípadne ďalší upresňujúci názov média.
- meno autora,
- meno vyučujúceho(ich), resp. meno vedúceho a konzultanta-ov pri DP,
- dátum odovzdania produktu,
- označenie čísla média v tvare <poradové číslo>/<celkový počet> (napr.: 1/1 pri jednom médiu, pri dvoch prvé bude označené 1/2, druhé 2/2 a pod.),
- prípadný krátky popis prístupu na médium (heslo, spôsob rozbalenia, druh použitého programového prostredia a pod.).
Média musia byť umiestnené v sprievodnej správe tak, aby nebolo možné ich samovoľné vypadnutie, napr. v prilepenej obálke k hlavnému textovému dokumentu.
Titulná strana príslušnej programovej dokumentácie. Číselný údaj znamená veľkosť písma, B znamená zvýraznenie:
<záhlavie: Názov
školy, fakulty, >
<katedry 14>
.
.
.
.
<stred strany: Názov programu 18 B>
<Druh príručky, napr.
"Systémová príručka" 14>
< charakter úlohy, napr
Názov predmetu 12>
.
.
.
.
<spodok strany - nasledujúce texty veľkosť 10:>
Dátum: <dátum>
Meno učiteľa: <meno vyučujúceho, ved.DP> Autori: <meno autora, roč./št.sk.>
Meno konzultanta:<meno konzultanta-ov, <meno autora, roč./št.sk.>
pri DP>
Súvisiace
štandardy KPI:
[1] Dokumentácia pre technické prostriedky a pre integrované prostriedky - 11
[2] Doplnok k programovej dokumentácii – použitie štruktúrovaného návrhu - 14
[3] Doplnok k programovej dokumentácii – použitie objektového návrhu - 15
[4] Pokyny pre vypracovanie diplomovej práce - 12
[5] Projektová dokumentácia informačného systému - 13
[6] Projektová dokumentácia počítačovej siete - 16
Zostavili:
Doc. Ing. Milan Šujanský, CSc. Doc. Ing. Zdeněk Havlice,CSc.
Ing. Branislav Sobota, PhD. Ing. Stanislav Šuba
Košice, 6.3.2000
