A dokumentáció

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ó?

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

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ó

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).

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.
  • 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.

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!

Share
This entry was posted in Módszertan, Programozás and tagged , , , , , , , , , , , , , . Bookmark the permalink. Follow any comments here with the RSS feed for this post. Post a comment or leave a trackback: Trackback URL.

Comments

  • ha használható a szoftver, akkor minimális user guide-ra szükség lehet, de az is jobbára hasznos, ha integrálódik a felülethez. Egyébként pedig szerintem felesleges user guide-ot írni.

    Jó cikk, gratula!

Leave a Comment


  • RSS JTechLog – Viczián István java blogja


    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693

    Warning: A non-numeric value encountered in /chroot/home/infokuka/infokukac.com/html/wp-includes/SimplePie/Parse/Date.php on line 693
  • RSS Tajti Ákos C és Java blogja

  • RSS QualityOnTime

  • RSS Adaptive PM

  • RSS Menedzsmentor blog

  • Shelfari: Book reviews on your book blog