Szoftverdokumentáció

Átírás

1 Szoftverdokumentáció Minden emberi használatra előállított terméket dokumentálni kell. Definíció: A dokumentum tényeket (adatokat) és/vagy szabályokat (eljárásokat, utasításokat, relációkat) tartalmazó, azonosítható, nyilvántartott információs objektum. A dokumentum formája (szintaktika), tartalma (szemantika) és felhasználási célja (pragmatika) előírt, szabályozott. A dokumentáció célja, hogy a termék életének különböző eseményeire tervezésre, gyártásra, értékesítésre, felhasználásra és karbantartásra vonatkozóan a termékkel kapcsolatban álló ember számára a szükséges információt tartalmazza. A szoftverdokumentáció a szoftvertermékeknek a program kódjával azonos fontosságú és ahhoz szervesen kapcsolódó összetevője. Sőt a dokumentáció minősége is legalább annyira fontos, mint magának a szoftvernek a minősége. A legfontosabb követelmények egyike a dokumentum olvashatósága, hiszen alapvető szempont, hogy azt ne csak a szerzője tudja elolvasni, hanem bárki, aki a szoftverrel foglalkozik. 1

2 Az olvashatóság mérésére Guning 1962-ben megalkotta a Fog indexet, amely a mondatok hosszán, és a nehéz szavak számán alapul, ahol a szó nehézségét a szóban található hangok száma adja. Dokumentációs szabványok A szabványok célja, hogy a tárgyukat képező dolgokra vonatkozóan a legfontosabb információk körét és formáját meghatározzák, lehetővé téve, hogy egyazon dolgon különböző emberek ugyanazt értsék, ami előfeltétele a széles körű felhasználásnak. A szoftverfejlesztés során különösen fontosak a dokumentációs szabványok, hiszen a szoftver és a szoftverfolyamat csak a dokumentáció alapján követhető. Háromféle dokumentációs szabvány létezik: 1. A dokumentációs folyamat szabványai: a dokumentum elkészítése alatt alkalmazandó folyamatokat a dokumentumfejlesztés eljárásait, a dokumentum-készítés szoftvereszközeit, a dokumentum magas minőségét biztosító ellenőrző és finomítási eljárásokat definiálják. E folyamat minőségi szabványainak rugalmasnak, és mindenféle dokumentum kezelésére képesnek kell lenniük. A dokumentumok szerkesztése, ellenőrzése átvizsgálása és újraszerkesztése iteratív folyamat, amely addig ismétlődik, amíg elfogadható minőségű dokumentumot nem kapunk. 2

3 2. Dokumentumszabványok: a dokumentum szerkezetét és megjelenítését írják elő. Ezeket a szoftverfejlesztés folyamán készített minden dokumentumra alkalmazni kell. Egységesnek kell lennie a dokumentumok stílusának, külsejének, valamint azonos típusú dokumentumok esetén a szerkezetnek is. 3. A dokumentumcsere szabványai: biztosítják, hogy a dokumentum minden elektronikus másolata kompatibilis legyen. A fejlesztői dokumentáció Minden szoftverfejlesztési fázisnak meg van a maga dokumentációja. A szoftver fejlesztését végigkísérő dokumentációk összességét nevezik fejlesztői dokumentációnak. A fejlesztői dokumentáció részei: a feladatspecifikáció, a programterv, a forrásprogram, a kész program, a tesztadatok listája. Ezeket a dokumentációkat a szoftver életében mindvégig meg kell őrizni, hiszen csak a dokumentáció segítségével lehet változásokat eszközölni a szoftveren. 3

4 A szoftverkövetelmények dokumentuma A szoftverkövetelmények dokumentuma nem más, mint a rendszerfejlesztőkkel szemben támasztott elvárások hivatalos leírása. Általában tartalmazza a rendszer felhasználói követelményeit, valamint a rendszerkövetelmények részletes leírását. A követelménydokumentumot használják a megrendelők, a menedzserek, a rendszertervezők, a rendszerteszt-tervezők, valamint a rendszerkarbantartás-tervezők. A megrendelők határozzák meg a követelményeket és ellenőrzik, hogy azok megfelelnek-e az igényeiknek, ha nem, akkor változtatásokat írnak elő. A menedzserek e dokumentum alapján készítenek árajánlatot, a fejlesztők pedig ez alapján készítik el a terméket. A felhasználói dokumentáció A felhasználói dokumentáció célja, hogy a termék rendeltetésszerű használatához szükséges valamennyi információt tartalmazza. Ezért a szoftver használata előtt a felhasználónak ajánlott áttekinteni ezt a dokumentációt. 4

5 A különböző csoportba tartozó felhasználók és a felhasználói szakértelem különböző szintjeinek kiszolgálása érdekében a szoftverrendszerrel együtt legalább öt dokumentumot kell elkészíteni : 1. Funkcionális leírás: leírja a rendszer által biztosított szolgáltatásokat. A bevezető kézikönyvet, amelyet elolvasva a felhasználó képes lesz eldönteni, hogy az adott rendszerre van-e szüksége. 2. Telepítési dokumentum: részletezi a rendszer telepítésének menetét. Leírja a lemezeket, amelyen a rendszer leszállításra került, az ezeken található állományokat, és a minimálisan szükséges hardverkonfigurációt. Tartalmaznia kell telepítésre vonatkozó utasításokat is, valamint azt, hogy hogyan kell a konfigurációfüggő állományokat beállítani. 3. Bevezető kézikönyv: egy kötetlen bevezetést tartalmaz, leírva a rendszer szabályos használatát. Le kell írnia, hogy hogyan lehet elkezdeni a rendszer használatát, és hogy a végfelhasználók hogyan vehetik hasznát a rendszer megszokott lehetőségeinek. A kézikönyvnek sok szemléltető példát kell bemutatnia, és információt kell tartalmaznia a hibák kijavításának és a hasznos munka újrakezdésének módszereiről. 4. Referencia kézikönyv: a rendszer lehetőségeit és azok használatát adja meg, leírja a hibaüzenetek listáját, a lehetséges okokat, valamint leírja, hogy adott hibák esetén mit kell tenni. 5. Egyes rendszerekhez adminisztrátori kézikönyv is csatolható. Ez a rendszer egy másik rendszerrel kölcsönhatásba lépésekor 5

6 létrejövő üzeneteket írja le, és azt, hogy hogyan kell azokra reagálni. Ha a rendszer hardveréről is szó van, ez a kézikönyv elmagyarázhatja, hogy hogyan lehet a hardverrel kapcsolatos problémákat felismerni és megjavítani, hogyan kell új perifériát csatlakoztatni stb. A felhasználói dokumentáció a szoftverdokumentáció azon része, amelyet a rendszer felhasználóinak a szoftver első használatakor érdemes áttanulmányozni, és részletesen megismerkedni vele. A dokumentumok minősítési szempontjai Akárcsak a szoftvernek, a szoftverdokumentációnak is eleget kell tennie bizonyos minőségi követelményeknek, ezért miután elkészítették a szoftvertermék dokumentumait, azt minősíteni is kell. Alapvető szempont, hogy a dokumentum a vonatkozó szabvány előírásait kielégítse. Ez azonban még nem elegendő, hiszen egy előírást kielégíteni több különböző módon lehetséges, és egy szabványelőírás nem teljesen konkrét, csak irányelveket ad. Minden dokumentáció minőségét az határozza meg, hogy felhasználási céljának milyen mértékben felel meg. 6

7 Szoftvertermékek esetén, mivel azok általában módosulnak, a dokumentumok használhatósági tulajdonságán kívül még egy szempont fontos, mégpedig a dokumentum karbantarthatósága. A használhatóság három összetevőre bontható, melyek a dokumentumok különböző tulajdonságait írják le. Ezek az összetevők a megbízhatóság, áttekinthetőség és érthetőség. Egy dokumentum megbízhatósága két szempontból vizsgálható: egyrészt, hogy tartalmazza-e a tőle elvárt és a tartalomjegyzékében szereplő információkat, másrészt pedig, hogy a kívánt információkat helyesen tartalmazza-e. Evidens, hogy egy dokumentáció megbízhatatlan, ha bizonyos tevékenységhez kapcsolódó információ nincs benne, vagy ha valótlan információt rejt magában. Azaz azt mondhatjuk, hogy egy dokumentum akkor megbízható, ha a szükséges információt helyesen tartalmazza. Egy dokumentum áttekinthetősége a meghatározott információnak a dokumentumból való kikereséséhez szükséges ráfordítással mérhető. 7

8 Ez egyrészt a kezelhetőségét könnyítő formális segédeszközök alkalmazásától (például: tartalomjegyzék, tárgymutató), másrészt a dokumentáció felépítésétől és tagolásától is függ. Az érthetőség az egyes kijelentéseknek és a teljes dokumentumnak az érthetőségéből áll össze. Az egyes kijelentések érthetősége a megfogalmazás világosságától és a szövegrészben való elhelyezésüktől függ, a dokumentum érthetőségét a didaktikus felépítés és a téma kezeléséhez szükséges információ teljessége határozza meg. Könnyen belátható, hogy a fent említett tulajdonságok gyakran átfedik, illetve kölcsönösen feltételezik egymást. Például: egy érthetetlen dokumentum egyben megbízhatatlan is, hiszen a szükséges információ adott idő alatt nem kereshető ki, vagy félreérthető, ami szintén a megfelelő tevékenység megtételéhez szükséges időt növeli. A dokumentum karbantarthatósága a változtathatósági tulajdonsággal jellemezhető. A változtathatóság a dokumentum karbantartásához szükséges ráfordítással jellemezhető. A változtathatóság nagysága az anyagban levő redundancia mennyiségével egyenesen arányos. Minőségellenőrzési módszerek A dokumentumminősítési szempontok teljesülése, illetve a szempontoknak való megfelelés mértéke nem állapítható meg 8

9 közvetlenül. Ezért a dokumentumok tulajdonságait további olyan jelenségekre kell bontani, melyek közvetlenül vizsgálhatók. A vizsgálandó jelenségek kiválasztásakor a gyenge pontokra való figyelemfelhívás, és a jelenségeknek egy tetszőleges dokumentumra érvényes rendszerezése az elsődleges kiindulási szempont. A jelenségek csoportosítása a dokumentáció dokumentum fejezet - kijelentés hierarchiát követi. A jelenségek rögzítésének és osztályozásának segédeszköze a hibalista. A hibalistában a hiányosságoknak három osztálya különböztethető meg az általuk előidézhető káros események súlyosságától függően, ezek: a súlyos, a közepes és az enyhe hiba. Súlyos hibáról akkor beszélünk, ha az általa dokumentált rendszer hibás alkalmazásához vezet. Közepes hiba az, amely kétséget ébreszt az olvasóban a dokumentum elkészítésének gondosságát, a benne található információ megbízhatóságát és helytállóságát illetően. Minden más hiba enyhe hibának számít. A kijelentésekre vonatkozó hibák lehetnek súlyos hibák (tényszerűleg hibás, nem teljes, nem világos, félreérthető, felületes, formálisan hibás), közepes hibák (nem biztosan elégséges, nyelvtanilag hibás) és enyhe hibák (a szóhasználat nem teljesen megfelelő, felesleges, túl részletezett). 9

10 A kijelentéseket egymáshoz való viszonyuk, környezetükkel való konzisztenciájuk szempontjából is vizsgálni kell. Ez a következő hiányosságok fennállásának ellenőrzését igényli: Súlyos hibák: ellentmondás valamivel, hibás utalás, hiányzó magyarázat; Közepes vagy enyhe hibák: a dokumentumban idegen a kifejezés, a magyarázat nem folyamatos, nem megfelelő a sorrend, nem egységes szövegezésű más kijelentéssel, nem egységes jelölésű más kijelentéssel, felesleges ismétlése valaminek. A következő vizsgálandó hierarchiaszint a fejezet. Ennél a következő, pozitív ismérvek meglétét kell ellenőrizni: teljesség, áttekinthetőség, a tartalom homogenitása, az ábrázolás pontossága, érthetőség az adott részen belül, témahűség, olvashatóság, a leírás pontossága. 10

11 A következő szint a dokumentum, amely fejezetekből épül fel. A dokumentumnak el kell különülnie a többi dokumentumtól, nyelvezetének igazodnia kell a felhasználó nyelvezetéhez. A dokumentumnak formailag, didaktikailag és logikailag is tagoltnak kell lennie, valamint teljesnek kell lennie. A legfelső szinten pedig a teljes dokumentáció szerepel. A dokumentációnak kezelhetőnek és összetételének megfelelőnek kell lennie. 11