A dokumentáció

infokukac.com/2009/07/a-dokumentacio

By Marhefka István 2009. 07. 30.

A szoftverfejlesztési projektek terméke nem csupán maga a szoftver, hanem annak

dokumentációja is. Dokumentációt általában azért kényszerülünk írni, hogy az ügyfél ez
irányú kérését kielégítsük, vagy pedig azért, hogy a cégünk belső szabályozásainak eleget
tegyünk.

A dokumentáció célja a szoftverrel kapcsolatos ismeretek átadása: követelmények és az

elvárt működés kommunikálása (pl. követelményspecifikáció, funkcionális specifikáció), a
különféle tervezési eredmények rögzítése (pl. logikai, fizikai rendszerterv), az elkészült
rendszer használatának bemutatása (felhasználói kézikönyv), üzemeltetéssel kapcsolatos
feladatok ismertetése (üzemeltetői kézikönyv), a projekt haladását ismertető
dokumentumok (státuszriportok) stb.

Mikor jó, ha dokumentációt írunk?

Még mielőtt rátérek a dokumentációgyártás-ellenes nézeteimre, le kell írnom, hogy a
megfelelő dokumentációkra igenis szükség van. Kiváló példa erre a felhasználói
kézikönyv. A felhasználói kézikönyvre egyszerűen szükség van. (Ámbár érdemesebb
feltenni magunknak itt is a kérdést: biztos, hogy a felhasználói kézikönyv a megoldás?
Nem jobb-e egy megfelelő oktatás, e-learning tananyag, inkább csináljunk-e on-line súgót
esetleg GYIK-ot? Egy felhasználói kézikönyvet nem olvas el az elejétől a végéig úgysem
senki.)

Az üzemeltetői kézikönyv is egy fontos dokumentum: az üzemeltetői állomány számos

emberből áll, akiknek több rendszert is kell egyidejűleg felügyelniük és üzemeltetniük. Ők
nem ismerik (és nem is kell ismerniük) a rendszer belső működését, de igenis tudniuk
kell, hogy milyen teendőik vannak, hogy biztosítsák egy rendszer folyamatos működését.
Ők tipikusan egy rövid, tömör dokumentumot várnak.

Ha egy dokumentumot akarunk készíteni, mindig őszintén tegyük fel magunknak a

következő kérdéseket:

Mi a célja a dokumentumnak?
Ki fogja (el)olvasni?
Lesz-e haszna?
Mi történik, ha mégsem írom meg?
Tényleg ez az az időpont, amikor meg kell írnom?

Egy dokumentáció jó megírása megfelelő képességet és gyakorlatot igényel. (Erről talán

majd máskor.)

Miért nem jó a dokumentáció?

1/6
A szoftver tervezési, implementálási döntéseit leíró dokumentáció elkészítése a
következők miatt problémás:

nem olvasható ki belőlük a szándék: a követelményspecifikáció nem írja le az

ügyfél szándékát, csak “bután” rögzíti az ügyfél oldaláról elhangzott összes
követelményt. A tervezéssel kapcsolatos dokumentációk szolgai módon igyekeznek
kielégíteni az ismeretlen kontextusban felmerült követelményeket, és a tervezési
döntések mögött meghúzódó gondolatmenetet, – ami a fejlesztő számára szükséges
lehet – nem kommunikálja. A fejlesztő így egy olyan anyagból kénytelen dolgozni,
amelynek hátterével nincs tisztában. (Ez azért fontos, mert ha enyhítenénk a
követelmények és tervezési döntések kényszerein, sokkal egyszerűbb és jobb
megoldáshoz juthatunk. A jobb megoldást úgy is lehet érteni, hogy ha egy funkciót
egyszerűen, gyorsan valósítunk meg, más fontos funkciók kifejlesztésére is több idő
jut.)
a követelmények (elvárások) _mindig_ változnak: ha következetesek és “up-
to-date-ek” akarunk maradni, akkor állandóan frissíthetjük a dokumentációt;
nem lehet előre jól (és nem is érdemes) megtervezni a szoftvert, túl komplex az
elvárt működés;
túl sok idő megy el a tervek elkészítésével ahelyett, hogy egy működő szoftvert
készítenénk, amit az ügyfélnek bemutatva azonnali visszajelzést kaphatnánk;
az ügyfél nem fogja megérteni a dokumentációt;
a fejlesztő nem érti meg a dokumentációt: ez lehet a dokumentációt készítő hibája, a
fejlesztő hibája (hiányossága), de általában egyik hibája sem. Ha az írott szöveg
túlságosan informális, akkor bizonyos részletek sínylődnek el, ha pedig túlságosan
formális, akkor már a lényeg veszlik el, ráadásul nem ad mozgásteret a fejlesztőnek.
Ki fog megérteni, és fejben tartani több száz oldalnyi írott szöveget?;
ha e-mailben, dokumentációkban kommunikálunk egymással, folyamatos a
félreértés lehetősége. Különösképp akkor bosszantó ez, ha csak későn derül ki, hogy
valamit félreértettünk.

Akik preferálják a dokumentumok gyártását, a következőkkel érvelnek:

Ha nincs leírva, mit kell csinálni,

hogyan állapodunk meg és számolunk el az ügyféllel?
hogyan lesz megtervezve a szoftver?
hogyan lesz lefejlesztve a program?
hogyan lesz letesztelve az elkészült szoftver?
hogyan tudjuk követni a projektet? Honnan tudjuk mikor leszünk készen?
Egyesek szerint olcsóbb, ha elkészül a részletes tervezési dokumentáció, mintha a
fejlesztés, tesztelés közben/után derülne ki, hogy valami nem megfelelően készült el.
Ha nagy csapatban dolgozunk, elengedhetetlen, hogy minden le legyen
dokumentálva.
Ha a fejlesztőt elüti a villamos, hogy fogják tudni folytatni a munkáját?

Dokumentációs elvárások minimalizálása

2/6
Egyszerűen vannak olyan helyzetek, amikor a dokumentáció elkészítése nem kerülhető ki.
Ha az ügyfél mindenképpen részletes dokumentációt akar, próbáljuk meggyőzni, hogy azt
utólag, a szoftver elkészítése után készítjük el, mert ő jobban jár, ha a többhónapos
tervezés helyett már egyből egy működő szoftvert lát. Az ügyfél üzleti megrendelőit
általában nem érdekli a dokumentáció, a szoftvert szeretnék látni, és minél hamarabb
bevezetni, ezért náluk kulcsoljunk. (Az ügyfél IT, PM, QA, SEC-es szakembereit nehéz
erről meggyőzni, de jó esetben az üzlet drive-olja a projektet, nem pedig a backend-
szervezetek).

Ha a cégünkön belül vannak dokumentációs elvárások, akkor indítsunk egy mozgalmat,

amivel elérhetjük céljainkat. Győzzük meg munkatársainkat, főnökeinket, hogy jobban
járunk, ha a dokumentációs rendet enyhítjük. Persze, ez óriásvállalatoknál, ahol
központilag szabályozzák a módszertanokat ez szélmalomharc lehet.

A dokumentációkkal szembeni elvárásokat csökkenthetjük, de ez önmagában nem

elegendő. Nagyon fontos, hogy a hagyományos szoftverfejlesztési módszertantól
elrugaszkodjunk, és egy jobb módszert találjunk a projekt közben kommunikáció
elősegítésére, jobbá tételére.

Cross-functional, kis létszámú csapat

Ahelyett, hogy fázisokra bontanánk a projektet, és az egyes fázisokhoz más-más
embereket rendelnénk (követelményfelmérés, -elemzés, tervezés, fejlesztés, tesztelés),
akik a fázisok között adják át a következő szereplőknek a tudást, hozzunk létre egy
olyan kis létszámú csapatot (max. 7-9 fő), amely a teljes projektet képes
véghezvinni (ezért cross-functional). A csapat nagy része fejlesztő legyen, akiknek a
program megírásán túli feladata az üzleti probléma megértése. Rengeteg
dokumentálás spórolható meg, a kommunikáció sokkal hatékonyabbá válik, mert a
fejlesztői csapat képviselői közvetlenül beszélnek az ügyféllel, és nincs szükség közbülső
szereplőkre, akik fordítanak az üzleti oldal és a fejlesztői oldal között. (És ezt ráadásul
dokumentációhegyekben kommunikálják.)

A csapatot célszerű egy projekt szobába ültetni, ahol a tagok bármikor, könnyen

információt cserélhetnek.

On-site customer
Az ügyfelet és annak üzleti problémáját ismerő személy (business expert) ideális esetben a
csapat tagja. Ha kérdés merül fel, a csapat bármelyik tagja közvetlenül hozzá fordulhat.
Nem kell levelezni, meeting-elni, workshop-olni, emlékeztetőket írni az ügyféllel, az
elvárások könnyebben formálhatóak át egy működő szoftverbe.

A kód maga a dokumentáció

3/6
Mi írja le a legrészletesebben a szoftver működését? A szoftver kódja maga. Törekedjünk
arra, hogy a forráskód jól szervezett, jól olvasható legyen! Ha ezt elérjük, akkor nem, vagy
csak minimális dokumentáció szükséges a program kódjához. A következők segíthetnek
abban, hogy a kód önmagát dokumentálja:

kódolási konvenciók,
code review-k,
_jó_ kommentezés,
folyamatos refaktorálás,
Test Driven Development (TDD).

A TDD alkalmazása kulcsfontosságú:

Az automatizált tesztek forgatókönyvként is felhasználhatóak. Egy-egy üzleti

forgatókönyv leírása mentén világosan látszik, hogy a szoftver mely részei érintettek
a funkciók megvalósításában, és azok hogyan működnek együtt egymással, hogyan
valósítják meg együtt a kívánt működést. Ez egy kiváló módszer, hogy végig
kövessük, mi hogyan működik a programban, és ezáltal a (teszt)kódban
dokumentáljuk a program működését. Új fejlesztői tagok bevonása esetén a tesztek
tanulmányozása, új tesztesetek megírásának kikényszerítése felgyorsítja az új
csapattag tanulási, beilleszkedési folyamatát.
A kód folyamatos refaktorálásával, átalakításával áttekinthetőbbé, érthetőbbé
tehető a kód. Ha a refaktorálás közben hiba csúszik be, akkor a tesztek (optimális
esetben) jelzik azt.
Megfelelően megírt automatizált tesztesetek esetén a manuális tesztelés feladatát
lényegesen leegyszerűsíthetjük, így a tesztelői csapat számára nem kell mindig a
teljes rendszer működését újra és újra ledokumentálni.

Egyszerű, átlátható módszerek a projektkövetésre

Tegyünk le arról, hogy a projekt elején megbecsüljük, mikorra leszünk kész, és hogy
pontosan tudjuk, mit fogunk megcsinálni! (Tudom, ez így messzire vezet. Olvassátok Csuti
blogját!) Helyette inkább alkalmazzunk olyan egyszerű módszereket, amelyek elősegítik a
projekt átláthatóságát, tervezhetőségét. A SCRUM eszközei lehetőséget nyújtanak rá:

Sprint és demó: az 1-4 hetes iteráció után az ügyfélnek bemutatásra kerülnek a

sprint során elkészült funkciók. Ennek közvetlen előnyei:
az ügyfél látja, mi készült el, és közvetlenül reagál rá (a státuszriportot lényegében
elfelejthetjük),
a tesztelői csapat is követni tudja, mi készült el, a tudást már menet közben
felszívják,
a fejlesztői csapat tagjai is követni tudják a rendszer fejlődését.
Reggeli stand-up: mindenki beszámol, mit tett előző nap, mit tervez mára, milyen
problémákkal szembesült.

4/6
 A product backlog: az összes előre látható feladat egy egyszerű táblázatban,
prioritás szerint van felsorolva. Folyamatosan követhető, mi készült el, és a
prioritások megfelelő változtatásával biztosíthatjuk, hogy időre elkészüljön egy
működő release.

Ezen módszerek biztosítják a projekt folyamatos személyes követhetőségét, és a

projektterv akár teljes mellőzését.

Belső wiki
Vannak olyan információk, amelyek nem forráskódban lelhetőek fel, de elérhetővé kell
őket tenni a teljes fejlesztői csapat számára. Ezeket célszerű wikiben tárolni. Többek
között mi erre használjuk a wiki-t:

az egyes sprintekhez készült demó forgatókönyvek tárolása (ezek mentén mutatjuk

meg az ügyfélnek az újonnan elkészült funkciókat),
fejlesztéssel kapcsolatos útmutatók, pl. kódolási konvenciók, Maven, SVN
tudnivalók, IDE beállítások,
a fejlesztéskor használt tesztkörnyezetek elérhetősége,
…

Nem egyszerű
Sok helyen hallani sem akarnak arról, hogy ne a hagyományos módon vezetett
projektmódszertanok szerint haladjunk. Az elvárás jogos: ha pontosan leírjuk a
követelményeket, akkor mindkét oldal el tud számolni egymással. Az ügyfél megmondja
mennyit hajlandó fizetni, a szállító pedig elfogadja (vagy nem). Később lehet tudni, hogy a
megrendelő mit követelt, és a szállító mit teljesített. Ha eltérés van, akkor azt kezelik.

A felelősség ezen a szinten jelenik meg először, és ez tovább gyűrűzik. Valaki leírta a
követelményeket, ő dolga végeztével átadja az elkészült anyagot a tervezőknek. Az ő
munkájuknak, és felelősségüknek ott a vége, hogy lerakják a tervezéssel kapcsolatos
dokumentációkat. A fejlesztők között kiosztják a munkát, mindenki a neki szóló
dokumentumrészt implementálja, azért felel. A tesztelők számára is elkészül a
dokumentáció, ami alapján a tesztelést végzik, ők ezért felelnek.

A szoftverfejlesztés extrém módon komplex, és magában hordozza az extrém

bizonytalanságot is. Lehetetlen előre rögzíteni a követelményeket, lehetetlen előre
tervezni, becsülni. Helyette olyan módszereket kell alkalmaznunk, amelyek képesek
alkalmazkodni a változásokhoz, és kezelhető velük a bizonytalanság.

Az írott dokumentáció helyett elő kell segíteni a verbális kommunikációt. Ez alapvetően

megváltoztatja a hagyományos módszertanok által sugárzott gondolkozást. Ha verbálisan
kommunikálunk, akkor ezt csak kislétszámú csapatban tehetjük meg. Ha nincs
dokumentáció, amit tételesen ellenőrizhetünk, hogy végeztünk-e a munkával, más
módszereket kell alkalmaznunk.

5/6
Számos kérdés merül fel, és jelenleg nincs általános megoldás. Mégis van egy kulcs:
önmagunk folyamatos megfigyelésével, értékelésével és tanulással mindig adaptálódjunk
az adott környezethez!

6/6