Dokumentálás

A program egy termék, és egy termékhez mindig tartozniuk kell különböző leírásoknak.

Mire is lehet szükség egy program kapcsán? Először is egy leendő felhasználónak el kell döntenie, hogy milyen programot, akar használni. Ha a programot megvette, akkor el szeretné helyezni a számítógépén, majd használni szeretné, és a felhasználásban segítséget vár.

Nemcsak a felhasználónak van szüksége dokumentációra, hanem a fejlesztőnek, karbantartónak is (nem véletlenül adnak például háztartási készülékeinkhez műszaki leírást is).

Nyilvánvaló, hogy ez a két- vagy többfajta dokumentáció másoknak szól, így nem egy egységes dokumentációról fogunk beszélni, hanem többfajta dokumentumról.

1. A dokumentáció fajtái

1.1. Fejlesztői dokumentáció

Minden egyes dokumentumnál fel kell tennünk azt a kérdést, hogy „Kinek szól?” Az e kérdésre adott válasz egyértelműen meghatározza, hogy az ilyen dokumentációban minek kell szerepelnie.

A fejlesztői dokumentációt használja az, akinek a programban hibát kell keresnie, a hibát ki kell javítania, a programot hatékonyabbra kell írnia, át kell vinnie más gépre, át kell írnia más nyelvre, valamint tovább kell fejlesztenie.

Az ő munkájuk megkönnyítése érdekében a fejlesztői dokumentációban szerepeljenek a következők:

• specifikációk, követelményanalízis (korlátozások, pl. megkívánt hatékonysági jellemzők, alkalmazandó adatszerkezetek). A feladat és a megoldástól elvárt követelmények meghatározása. Ezt még a feladat kitűzője adta, vagy vele történt megbeszélés során pontosodott a megoldás első lépéseként;
• a futási környezet leírása: számítógép, operációs rendszer, memóriaméret, (speciális) perifériaigény, grafikus kártya (felbontóképesség, színek száma …) stb.;
• fejlesztői környezet leírása: a választott programnyelv(ek), és verziószáma(i); eljáráskönyvtárak, unitok (azaz a szükséges „programdarabok” fájljai);
• az algoritmusok és az adatok (típusok, osztályok, programkonstansok) leírása, ezek kapcsolata. Döntések, más lehetőségek, érvek, magyarázatok;
• kód, implementációs szabványok (ún. kódolási szabályok, egyéni konvenciók), döntések;
• tesztesetek, azaz milyen (jellegzetes) bemeneti adatokra, milyen eredménnyel „válaszol” a program;
• hatékonysági mérések (hatékonysági tesztesetek), megfontolások, javaslatok az esetleges hatékonyabbra írásra;
• fejlesztési lehetőségek;
• a készítő adatai.

A programkészítés közben keletkezhetnek olyan dokumentumok, amelyek az elkészítést támogatják, majd lényegük később beépülhet a fejlesztői dokumentációba. Ezek többek között a következők:

Koncepcióterv

Feladata a probléma lehetséges megoldásainak bemutatása és értékelése. Felhasználásával a feladat kitűzője választhat megoldási lehetőségek között.

Rendszerterv

Tartalmaznia kell a szükséges hardver-szoftver környezet leírását, amely meghatározza a rendszer használhatósági körét. Itt konkrét döntéseket kell megfogalmazni, következményeikkel, indoklásukkal együtt. Ez az a dokumentum, amelynek alapján a tényleges programozási munka elkezdődhet.

1.2. Felhasználói dokumentáció

Ezt a dokumentumot használja a felhasználó, az üzembe helyező, a betanító.

Nekik szükségük van a következőkre:

• a feladat – egy rövid összefoglaló leírás is kell az áttekintés miatt és egy részletes a pontos használathoz;
• a futási környezet leírása: számítógép, operációs rendszer, memóriaméret, perifériaigény, grafikus kártya, ... (megegyezik a fejlesztői dokumentáció ugyanilyen című részével);
• a használat leírása – hogyan kell a programot betölteni/elindítani, milyen kérdéseket tesz fel, mik a lehetséges válaszok, mik a program egyes lépései, lehetőségei (nagyvonalú funkcionális leírás);
• bemenő adatok, eredmények, szolgáltatások részletes leírása: mit, mikor, milyen sorrendben kell megadni (részletes funkcionális leírás);
• mintaalkalmazás – példafutás. A felhasználó – főleg a betanító – ennek alapján tudja előre – gép nélkül – „elképzelni” a programot;
• hibaüzenetek és a hibák lehetséges okai – mi a teendő valamely hibaüzenet láttán.

Látható ebből, hogy a felhasználói és a fejlesztői dokumentáció több közös jellemzőt tartalmaz.

1.3. Programismertető

A programismertető célja a vásárló, programkereső ember meggyőzése arról, hogy e program felel meg leginkább igényeinek. Ez a hangzatos, reklám jellegű stílus mellett a következőket igényli:

• a feladat rövid, szöveges leírása, áttekintési céllal;
• a program tulajdonságainak rövid leírása.
• minimális hardver és szoftver (operációs rendszer és az esetlegesen megkívánt egyéb, a programmal együtt nem „szállított” szoftverkellékek, pl. driverek, dll-ek stb.) környezet.

1.4. Installálási kézikönyv, operátori kézikönyv

Nagyobb programok esetén külön installálási (üzembe helyezési) kézikönyvet mellékelnek, máskor ez a felhasználói dokumentáció része. Ebben szerepel mindaz az információ, aminek segítségével egy-több generáló lemezről a program elhelyezhető a gépünkön úgy, hogy az aktuális környezetben optimálisan működjön. (Ügyelni kell arra, hogy az installáció minél kevesebb számítástechnikai ismerettel végrehajtható legyen! Fel lehet használni olyan célprogramokat, amelyeket kifejezetten erre terveztek, de legalább egy batch programmal automatizálni kell. Ilyen automatizmus esetén is dokumentálni kell az installációs folyamat lépéseit.)

Az operátori kézikönyv olyan rendszereknél különül el a felhasználói kézikönyvtől, ahol más a program felhasználója és más a kezelője.

Vissza a tartalomjegyzékhez

2. A dokumentáció tulajdonságai

2.1. Szerkezet

A dokumentáció elsődleges célja segítségnyújtás a program leendő felhasználóinak, továbbfejlesztőinek. Ezért olyannak kell lennie, hogy minden számukra szükséges tudnivalóhoz könnyen hozzájuthassanak. Ehhez elsődleges szempont természetesen, hogy a dokumentáció mindezeket tartalmazza, de a használatát egyéb követelmények betartásával jelentősen megkönnyíthetjük. Ezek a következők:

• a dokumentáció ne legyen túl hosszú, hiszen egy program használatához senki sem akar egy „regényt” elolvasni;
• a dokumentáció ne legyen túl rövid, mert akkor tömörsége miatt érthetetlen lesz, s így használhatatlan;
• a dokumentáció legyen világosan tagolt, és a tagolás segítse elő az egyes tudnivalók gyors keresését;
• a dokumentáció legyen tömör: az olvasója ne vesszen el a részletekben;
• a dokumentáció legyen olvasható: a túlságos (és kizárólagos) formalizálás az érthetőség rovására megy;
• a dokumentáció legyen pontos: az olvasója minden kérdésére tartalmazza a választ.

2.2. Forma

A dokumentáció használatát néhány formai jellemző nagyban megkönnyítheti. Ezek egyike a tartalomjegyzék. Másik, dokumentációkban ennél ritkábban használt, de néha kifejezetten nagy segítséget nyújtó eszköz az index.

Az nyilvánvaló, hogy világos szerkezetű kell legyen: kitalálható mondanivalójú fejezetekre bontva. További stílusjegyek megegyeznek bármely szakmai kiadványéval.

2.3. Stílus

Végezetül essen néhány szó az egyes dokumentációk stílusáról! A programismertető egyértelműen reklámcélra szolgál. Itt dicsérni kell a programot, kiemelve jó tulajdonságait.

A felhasználói dokumentáció elsősorban részletes szöveges leírás, amely időnként lehet „szájbarágó” is. (Célszerű figyelembe venni a várható felhasználói kört a leírás részletességének, a szájbarágósság szintjének megtervezésénél. Például teljességgel fölösleges egy Windows környezetben futó program esetében az ablakkezelésről általánosságban szólni.)

A fejlesztői dokumentációban minden más szempontnál fontosabb a pontosság, emiatt ebben kerülhet elő a matematikai leírás, a formális specifikáció.

Az installálási, illetve az operátori kézikönyv elsősorban utasítások, teendők pontos felsorolása, utalva a lehetséges válaszok következményeire.

Az animáció bemutatja a dokumentálással kapcsolatos alapvető ismereteket.

Vissza a tartalomjegyzékhez