Skip to Main Content

Content

Hogyan (ne) dokumentáljunk?
Pataki Dávid 2021.01.06

A dokumentáció legfőbb célja, hogy legyen. Ami pedig a leggyakoribb, hogy nincs.

Ennek megfelelően mindenki vágyik rá, hogy legyen, de olyan ember a cégen belül, aki normálisan megcsinálja, nincs.

A fenti ellentmondás a húszéves vállalkozói illetve programozói létem alatt folyamatos feszültséget okozott bennem, illetve ez az egész problémakör mindig Damoklész kardjaként lógott felettem. 

Amikor már alkalmazottaim lettek, a "jó lenne ha írnál doksit" bátortalan óhaj folyamatosan fordult át határozott kéréssé végül pedig fulladt reménytelen várakozásba. Végülis minden vezetőnek vannak gumicsontjai, miről másról mondjon le, ha nem a dokumentációról, nem? Nem.

A tapasztalatom az, hogy minden ajánlatban benne kell legyen, hogy írsz dokumentációt. Aztán nem olvassa el senki. Végülis bármilyet írhatsz, nekem még soha senki nem tette szóvá hogy nincs (lehet azért, mert volt) vagy nem tetszik. Mindenki utál olvasni, szöveget értelmezni. Csak fusson a kód meg legyen jó a riport. 

Aztán ott van az a tény is, hogy minden változik, fejlődik. Ugyan ki fogja a doksiban a változásokat átvezetni? Ha egyáltalán az első fejlesztést követően készült is valami, csak hogy ki legyen fizetve a pénz, az jó eséllyel örökre úgy is marad. Mint egy honlap, amit három éve nem frissítettek. Inkább törölnék az egészet, ahelyett, hogy ezzel égetik magukat.

Végül pedig hogyan is nézzen ki a dokumentáció? Valaha, valahol, valaki kapott egy mintát, hogy tessék, ez az elvárás, így kell ennek kinézni? Vagy láttál már olyat, ami tetszett? Meg amúgyis ott a kód, olvasd el, fejtsd vissza.

Miről szóljon a dokumentáció?

Számomra az első és legfontosabb szempont a dokumentáció írásánál az, hogy ha valaki teljesen újként a témában ideülne mellém, mi az, amit elmondanék neki. Mi a folyamat, ki vagy mi mit csinál és miért csinálja? Legyen folyamatábra. A dokumentáció adjon egy képet az összefüggésekről, ennyi talán elég is. 

Legalábbis ezeknek a kérdéseknek a megválaszolása a legfontosabb tartalmi elvárás. Mindig ezeket tedd fel magadnak újra és újra.

Milyen készségek kellenek a jó dokumentáció íráshoz?

Először is tanulj meg vakon gépelni. Én ezt a lépést 14 évvel ezelőtt tudtam le a Gépírás 2000 nevű CD-ROM megvásárlásával és esténként történő gyakorlásával. Ugyanakkor lassan eljutok odáig, hogy a háromhónapos próbaidő végére, aki erre nem képes, attól inkább jobb elbúcsúzni. Enélkül nem fog menni.

Másodszor meg kell tanulni a szakmai nyelvezetet és a mondatalkotást. Sokat kell olvasni. Kerülni kell az ami, aki, amely, dolog és hasonló töltelékszavakat. 

Például "a raktárból feltöltésre kerül a fájl a rendszerbe" mondat helyett az álljon, hogy "a raktár beszerzési osztályának munkatársa a rendelési adatokat tartalmazó EPS fájlt naponta öt és hat óra között betölti az DEPO-X rendszer rendelési moduljába a rendelések feltöltése menüpont alatt".

Harmadszor kezdd el. Először vért fogsz izzadni (pisilni), aztán még egy pár hónapig kitart ez az állapot de aztán lassan elkezdenek jönni az eredmények is.

Miért ne mondj le a dokumentációról?

Azt gondolom, ez a szakmai igényességed része kell, hogy legyen. Én sosem játszottam arra, hogy minden a fejemben van és így legalább nehezebben fognak kirúgni. Az a korrekt, ha a munkával együtt átadod a tudást is. Elolvasni úgysem fogják, cserébe jobban fognak szeretni, mert meglesz a tudat, hogy van. 

A második dolog, ha neked kell átvenni más munkáját, mert elmegy, megbetegszik, gyereket szül vagy világkörüli útra indul, ott a nyomás, az elvárás, hogy oldjad meg a feladatot. Nem lenne jobb, ha rádhagyományozta volna rögzített formában a "mi a folyamat, ki vagy mi mit csinál és mért csinálja" típusú kérdésekre a választ?

Végül pedig a megrendelő és a beszállító is hatalmas kockázatokat fut. 

A megrendelő azért, mert bármikor elveszítheti a beszállítót, vagy a beszállító mondja holnaptól, hogy akkor legyen az annyi kétszerannyi. 

A beszállító azért, mert ha otthagyja a csúcsszuper kollégája (annyira azért nem csúcsszuper, mert nem írt doksit) akkor most mi is a teendő? Adódik a kérdés.

Összességében nem értem, hogy miért vállalunk ekkora kockázatokat. Miért nem képes senki - tisztelet a kivételnek - ezt a műfajt elfogadható szinten űzni?

Én most a videó dokumentációval kísérletezek. Lehet, ez lesz a jövő. Nemtudom. 

De nem fogom feladni.