A dokumentáció valószínűleg egyidős az iparral. Amióta a szerszámok készítése, üzemeltetése és használata szétvált, valamilyen módon le kell írni, hogy adott eszköz hogyan működik, milyen gyakran és hogyan kell karbantartani, illetve hogyan kell használni. A faéknél ez viszonylag egyszerű, a szoftvereknél valamivel bonyolultabb – és ma már valószínűleg sokkal többen dolgoznak szoftverekkel, mint faékkel vagy kalapáccsal.

Az alkalmazások készítésének és üzemeltetésének kulcsa a dokumentáció, amióta fejlesztenek szoftvereket, azóta elengedhetetlen tartozékuk a dokumentáció. Mégis talán ez az egyik leggyűlöltebb feladat, amit aztán minden érintett tologat maga előtt, amíg aztán mindenki megfeledkezik róla. Aztán ha kifutott a projekt, ember sem lesz rá, hiszen pénzt sem lehet mögé tenni.

Pedig hiánya elég gyorsan kiderül: az alkalmazásüzemeltetést másik szolgáltató veszi át, vagy elmennek a cégtől azok, akik töviről-hegyire ismerik a rendszert, és az új kolléga legfeljebb az Einsteinnek tulajdonított bon mot-ba kapaszkodhat: "Csak egy őrültnek van szüksége a rendre, egy zseni uralja a káoszt."

Alapvetően két típusa létezik: a projektdokumentáció a fejlesztéshez, valamint az üzemeltetési dokumentáció. Hogyan lehet elérni, hogy ezek a létfontosságú dokumentumok elkészüljenek?

Legyen célratörő!

A terület szakértői szerint az egyik alapszabály, hogy a dokumentációban ne akarjuk a világmindenség működését rögzíteni, azaz csak az legyen benne, amire valóban szükség van. És persze vannak formai alapkövetelmények is: felépítése legyen logikus, az aktuális verzióról szóljon, és követhetők legyenek benne a változások, lehessen keresni a szövegeknek, sőt ha vannak, az ábráknak is. A projekttámogató eszközök nem véletlenül tartalmaznak olyan segédletet, amellyel menet közben, a fejlesztéssel párhuzamosan lehet felépíteni a dokumentációt.

Ennek ellenére sokszor még az üzletileg kritikus rendszerek dokumentációja is erősen hiányos. Emígyen pedig használhatatlan, ami persze rendre éles helyzetben derül ki. Pontos adatok nincsenek, de például a Computerwoche egy a témával foglalkozó cikke szerint az üzletileg kritikus alkalmazások üzemeltetéséért felelős vezetők többségének az a véleménye, hogy a működtetést segítő dokumentációk nem sokat érnek. Az, hogy nagyságrendileg egy fejlesztési projektek teljes költségének 5-10 százalékát emészti fel, hogy a dokumentációt napra készen tartsák, elég sok mindent megmagyaráz. Minden 100 forintból 10 menjen egy teljesen improduktív tevékenységre?! Na, ne!

Általánosságban kétféle dokumentációt kell készíteni: az alkalmazásdokumentáció leírja egy alkalmazás aktuális állapotát, a projektdokumentáció pedig a változásokat próbálja nyomon követni. Míg előbbi statikus állapotot ír le, utóbbi a fejlesztés során a kreatív és kooperatív folyamatait hivatott segíteni. Bár a kettő nem független egymástól, nem helyettesíthetik egymást.

Az alkalmazásdokumentáció rögzíti, hogy adott alkalmazás hogyan támogat egy üzleti folyamatot, leírja az egyes funkciókat, a követelményeket (pl. szabályozott környezetben). Tartalmaz kontextus- és komponensdiagramokat, leírja a műszaki architektúrát, a regressziós tesztelés folyamatát stb. Része továbbá az üzemeltetési és a felhasználói kézikönyv.

A projektdokumentáció ezzel szemben olyan elemekből áll, mint a követelmények leírása (esetleg felhasználói történetekkel kiegészítve), a követelményspecifikációk, a funkcionális specifikációk, a tervezési és műszaki specifikáció, az adatbázis-modell, az osztálydiagram, a tesztesetek és a tesztdokumentáció, valamint a verziókövetési dokumentáció.

És hogyan lehet ezeket előállítani?

Bár az alkalmazás- és a projektdokumentáció célja és elemei is eltérnek, mégsem teljesen független a kettő egymástól. Az alkalmazás aktuális állapotának leírása ugyanis előállítható a projektdokumentációból is, annak egyfajta letisztított gyűjteményeként is előállhat. Ez egyszerűsíti az alkalmazásdokumentáció előállítását, de nehezíti annak használatát. Ha például azt szeretnénk kideríteni, hogy egy funkciót miért úgy valósítottak meg, addig kell visszalépkedni a teljes dokumentációban, amíg meg nem találjuk a funkció telepítésének leírására.

De van előnye is ennek a módszernek: az állandó dokumentáció minden egyes változtatás után frissül a releváns információkkal. Ugyanakkor azt is figyelembe kell venni, hogy ha a fejlesztők dokumentálnak, jellemzően a lényegre szorítkozzanak, belső szakzsargonnal, amit a felhasználók nem feltétlenül tudnak dekódolni.

Szintén fontos kérdés a formátum. Kézenfekvő lenne például Word formátum, amit meg lehet osztani pl. a SharePointon. Ha azonban sok önálló dokumentum van, az nehezíti a keresést, főleg ha a dokumentumok nincsenek szervesen összekapcsolva (linkelés) egymással.

De akkor hogyan és mit?

Mit tartalmazzon egy dokumentáció? Mindenekelőtt az alkalmazás funkcióinak tömör leírását: mit csinál, milyen üzleti folyamatot támogat, milyen funkciókkal? Fontos a funkciókhoz tartozó követelmények felsorolása, mert az segíti megérteni, hogy miért van szükség egy adott funkcióra.

Benne kell lennie a műszaki architektúra leírásának (hogyan épül fel a rendszer). Ez a legjobban a kontextus- és komponensdiagramokkal oldható meg, esetleg a műszaki architektúra átfogó ábrájával kiegészítve.

Szintén elengedhetetlen a regressziós tesztesetekre vonatkozó leírás, amely növeli a a változtatásokat végrehajtásának biztonságát. Biztosítható például, hogy egy változás ne borítsa meg az alkalmazás funkcionalitását.

Ebből következik, hogy ha a projektdokumentáció felhasználásával szeretnénk egyszerűsíteni az alkalmazásdokumentáció előállítást, előbbinél is figyelni kell néhány kritériumra, mindenekelőtt a formai kérdésekre: új és módosított követelmények leírásának konzisztensen követnie kell az alkalmazásdokumentáció szerkezetét. A diagramok esetében érdemes kiindulni az alkalmazásdokumentációból: például az ott használtakban feltüntetni – kiemelni színnel vagy tipográfiai elemekkel – a változásokat. Emellett rögzíteni kell a műszaki architektúra módosításait, a követelményekre vonatkozó teszteseteket (beleértve a regressziós teszteseteket is).