Dokumentációk használata az IT-ban, csapaton belül

Post-surgical deaths in Scotland drop by a third, attributed to a checklist (bbc.co.uk)
https://news.ycombinator.com/item?id=19682451
https://www.bbc.co.uk/news/uk-scotland-47953541

->

Informatikában, ha egy csapatnak kb. ismétlődő feladatai vannak (pl.: beszélünk gépek sw-es építéséről, távoli üzemeltetéséről) miért olyan nehéz követnie, készítenie dokumentációt?

Ahány multinál jártam idáig, nemzetiségtől független, sose láttam azt, h. általános lett volna az a számomra alap hozzáállás, h. természetes, h. le vannak írva a processek és szigorúan követi is az ember őket, karbantartja, publikálja a csapatnak?

Pl.:
- step-by-step leírás követése, még ha 100-adszorra is végzed a feladatot
- troubleshooting, lessons learnt összesítő, ami kb. minden eddigi hibát leír (problem/solution szinten)

->

továbbra is azt látom h. visszajönnek az emberkék:
- "jaj, vmi nem működik" -> root cause: képtelen volt követni a step-by-step leírást
- "jaj, mi ez a hiba" -> le volt írva az is a troubleshootingban

Vagy más megközelítés: féltik az állásukat? h. ha dokumentálva van minden, akkor már könnyen lecserélhetők? sose kaptam őszinte választ. van 5000 másik mhely, ha ez tényleg igaz lenne.

Hogyan lehet rávenni az embereket h. használjanak és készítsenek dokumentációkat? Akár alap, akár komplex dolgokról az IT-ban?

Hozzászólások

Amit századszorra is ugyanúgy, gondolkodás nélkül kell elvégezni, azt nem dokumentumálni hanem automatizálni kell. :)

+1

Egyébként a kedvenc Facebook posztom a vikről, amikor valaki megkérte az schsokat, hogy töltsenek le neki valamit az egyetemi hálóról, s tolják fel neki Facebookra, mert se a step by step vpn telepítést, se az webes proxyt nem tudta használni... Szóval előbbi is csak addig működik amíg fogékony rá az akinek használnia kellene majd később...

A szoftver változik -> a dokumentáció hamar elavul. Persze karban lehetne tartani, de az uncsi és amúgy sincs rá idő :/
Nagyon ritka, hogy századszor is valami ugyanúgy működik. Linuxnál viszonylag egyszerű visszafejteni a dolgokat, ha van ssh log... A jó kód is önmagát magyarázza... az egy évvel ezelőtti persze kevésbé... de ha valamit csak évente használsz, akkor már igazoltad is magadnak, hogy annyira nem fontos dokumentálni (persze könnyen lehet, hogy 10 perc dokumentálással évente megspórolnál egy napot... de milyen messze van az az egy év... ki tudja, megérjük-e egyáltalán :) )

Szerencsére abban a helyzetben vagyok, hogy jelenleg még nem én vagyok az, aki mindent tud. A dokumentációt én is csak olvasom. Sokat linkelek másoknak, mikor segítséget kérnek, de legfeljebb a karbantartásban segítek picit dokumentálás terén, ha valami furát találok.

Amúgy pont a pilótáknál igazolták, hogy a listák használata túlságosan automatizálja az agyműködést, ami annyit tesz, hogy mikor megszoktad, hogy valami zöld és azt mondod az irányítótorony kérdésére, hogy jó, akkor simán lehet, hogy piros és rossz, csak mivel már megszoktad, ezért fel sem tűnik, hogy nem jó. Tudtommal ezt úgy próbálják kivédeni, hogy mindig más sorrendben mennek végig a listán. ( Fix me if I'm wrong )

Szerintem a szokásos dolgok itt is működhetnek: Definition of Done, Feladatok priorizálása, Brainstorming arról, hogy ez elmúlt hétből mit lehetne esetleg dokumentálni. Ha az emberünkön nincs ott a nyomás, hogy csinálja a következő feladatot, hanem van lehetősége kicsit megpihenni és ünnepelnie, hogy valamit megoldott, befejezett és működik... talán... de igazából magamon is azt veszem észre, hogy mikor megoldok egy problémát, akkor ráeszmélek, hogy tökjó, de akkor most kéne elkezdeni az igazi munkát, mert mindez csak azért volt, hogy előkészítsük a terepet valami másnak :)

Tudtommal ezt úgy próbálják kivédeni, hogy mindig más sorrendben mennek végig a listán.

Nincs ilyen eljárás, mivel a checklistek elemei egymásra épülnek, a legtöbb esetben elengedhetetlen a megfelelő sorrend, nem rakhatom ki a futóművet bármikor, csak x fékszárnyállásnál, stb.
Az, hogy az ember egy idő után túlzottan automatikusan fogja csinálni a műveleteket, tény, volt is belőle pár (bal)eset.

Munkaköri leírásba beleírni, meglétét ellenőrizni, hiányát számonkérni. Ha nem kényszer, nem fogják megcsinálni, ilyen egyszerű.

---
A Linux nem ingyenes. Meg kell fizetni a tanulópénzt.
Az emberek 66 százaléka nem tud számolni! Gondoljatok bele, ez majdnem a fele!!
Mindenki jó valamire. Ha másra nem, hát elrettentő példának.

Hogyan lehet rávenni az embereket h. használjanak és készítsenek dokumentációkat?

Szerintem a főnöke utasítása rá, hogy havonta meg kell csinálni 3 step-by-step leírást, és ezt következetesen ellenőrizze le.

Aztan fogja magat az ember, es atmegy olyan helyre, ahol nem baszogatjak ilyenekkel.

En egy dolgot tudok elkepzelni, mint megoldas: olyan dokumentacios/informacios rendszert kell letrehozni, amit nem fajdalmas hasznalni, sot mi tobb, hasznos az emberek szamara!

Random webappot sajnos fajdalmas, mar a bongeszo limitaltsaga miatt is. Egyetlen lehetoseg az az APIk hasznalata, es nativ vekony-kliens irasa.

es lehetoleg self hosted versiont, nalunk confluence van, de az elmult egy evben a kozepesen hasznalhatobol eljutottak a hasznalatatlan allapotba (user friendly menu, amit nem tudok ertelmezni, user friendly szerkeszto, amiben lassan semmi kicsit is komolyabb formazast nem lehet megtenni )

Mondjuk a dokumentációhoz szerintem az sem árt, hogyha a feladat elején van specifikáció :D
Mert amikor a káoszból csinálnak valamit és élő ember nem tudja, hogy sikerült eljutni odáig és miért működik, akkor azt dokumentálni is nehéz. Meg persze ahol rögtön dobják másik feladatra, ha már fél lábon áll a rendszer, akkor sosem lesz idő rendesen segédanyagot készíteni.

"amikor a káoszból csinálnak valamit és élő ember nem tudja, hogy sikerült eljutni odáig és miért működik" - ezt úgy szokás megoldani, hogy a kialakítás során a lépéseket _is_ dokumentálják, leírni, hogy az emzéperix parancsnak a --piroskaesafarkas= nem dokumentált paraméterét használva mesés erdeményt lehet elérni, és hasonlók.
Ez akkor is hasznos/kell, ha jellemző a területre, hogy "rögtön dobják másik feladatra, ha már fél lábon áll a rendszer" - ugyanis azt, amit csinált, valakinek tovább kell vinnie.

Sajnos nagyon sok olyan helyhez volt szerencsém, ahol "kilóra" készült "mit fogunk csinálni", illetve "hogyan kell majd üzemeltetni" doksikból kellett volna dolgozni, miközben a valós implementáció n+sok (nem dokumentált) részen tért "csak" el a kilós doksitól. Ilyen helyen kincs tud lenni a root/alkalmazásgazda shell history-ja, egy csomagtelepítési log, meg mindaz, ami a tényleges munka során keletkezik, mint írásos anyag.

Az már remek, ha van bármilyen doksi... a volt főnököm nevelte belém a step-by-step doksiírást, eleinte lázadtam ellene, de lassacskán felfogtam, hogy ez tényleg hasznos.
Írja le mindenki a saját doksiját, ugyanis nem biztos, hogy amit én írok, az másnak is hipphopp érthető lesz. Az alap megvan, tegye hozzá a sajátját a kollega, és hagy tényleg csapat vagyunk, akkor lassan összehozzuk az igazi dokumentációt, ami egy amőbányi aggyal rendelkező emberkének is megfelelő :)

Én az tapasztaltam a multiknál, hogy egy adott osztály pl. tízfős gárdájából egyetlen ember tudott mindent, a maradék kilenc pedig lógott rajta, mint borjú az anyján, és annyi agyuk sem volt, hogy felfogják a doksit, nemhogy hozzáadjanak :)

Doksi kell... de az esetek 90%-ban túlbonyolított processzek vannak és/vagy elba*zott architektúra, projekt szetup vagy akármi ilyesmi. Erre a megoldás nem az, hogy vaskos doksikat gyártunk, hanem olyan architektúrát/infrastrukturát építünk ami:

- konvenciókat követ
- amennyire lehet megfelel a standardoknak
- mentes a felesleges tooloktól, frameworkoktól, technológiáktól és komponensektől (a hobbijában mindenki olyan fancy és új trükköket vezet be amilyet csak akar, a melóban a lehetosegekhez kepest unalmas és faék egyszerűségű dolgokkal szeretnék találkozni)

Természetesen ez nagyfokú és könyörtelen fegyelmezettséget követel és az egész szakma tele van olyanokkal akik csak beleürítenek a dolgokba. Meg agilitással: mindenki azt csinál és úgy ahogy akar. Meg persze, ha ő beletesz valami csavart az neki nem probléma, mert ő érti - és számára nem érték az, hogy mások azzal meg küzdeni fognak vagy épp nem értik. Önzőség? Gyarlóság? Nem-törödőmség? Lehet. Ezeknek a kifésüléséhez az első lépés természetesen lehet egy doksi... de többnyire egy félig se áptudét doksi szokott lenni a végállapot. Ha valaki azalapján végignyomja a dolgokat - és találkozik 3 dologgal ami már nem úgy van vagy hiányzik arra már sz*rik rá hogy hozzáadja/átírja:

- neki ettől már nem lesz jobb
- egyeztetni kell másokkal, mert mi van ha az ő esete speciális
- szívjon más is, ha már engem leszo*attak
- különben is rohamléptékben kell haladni a feladattal és a menedzser/ügyfél azt akarja látni hogy haladnak a feladatok, nem az hogy közvetlenül értéket nem teremtő dolgokkal sza*akszunk

Azt hiszem megint optimista lábbal keltem fel. :)

Jelen esetben az, hogy mit jelent nekem es esetleg masoknak az ket kulonbozo dolog - igy en sem csodalkozom ilyen esetekben az "agilis"-eredmenyeken.

Majd egyszer olyan helyre kerulok ahol ez a ketto egybevag, de addig meg sokszor felmondok es/vagy jo sok projektre rakerulok. Az is lehet, hogy nekem vannak specialis elkepzeleseim vagy irrealis elvarasaim. Sajnalatos, hogy ezek csak hetekkel/honapokkal a munka/projekt kezdete utan derulnek ki igazan. Lutri az egesz. :)

Mikor volt olyan, hogy barmelyik munkaltato bevallotta, hogy szet-van-k*rva minden es ezen nem is szandekozunk valtoztatni, mert a legfontosabb, hogy meg a mai nap a legtobb penzt termeljuk a legrovidebbtavu gondolkodassal? (A kerdes koltoi)

Szerintem egyrészt pontos, mások számára könnyen érthető és követhető doksit írni rutinból az egy skill, ez nem olyasmi, ami megy egyből bárkinek. Szóval ezt valahogy úgy lehetne bevezetni, hogy be kellene gyakoroltatni mindenkivel és az eredményt reviewzgatni. És az is kellene, hogy nem mindenki annyiféleképpen írja ahogy gondolja, hanem valami egységes nyelv és módszertan kialakuljon egy szervezeten belül. És még ehhez kell az is, hogy könnyen meglegyen az adott doksi, ha kell, ami azt is jelenti, hogy rendben kell tartani az elhelyezés módját is. Meg persze mindent karban tartani. Ami azt jelenti, hogy ha valami megváltozik, akkor tudni melyik doksikat érinti és azokat updatelni. Ez az egész meg már jó sok erőforrás.

Szóval szerintem a fő ok az, hogy ez egy komplex feladat. És nem nagyon van tudás, tapasztalat és erőforrás hozzá.

Nálunk napi rendszerességgel:

- Leírom a hiba megoldását (plusz egy szájbarágót)
- Elküldöm a megfelelő (pl desktop support) csoportnak
- Vissza se jeleznek, hogy köszi vagy valami, de azonnal felhasználják legalább
- 1-2 órán belül rájönnek, hogy a dolog 3 percnél több időt vesz igénybe, ezért 600 címzettnek levelet írnak, hogy mivel ez a kb 1200-ból 10-12 pc-t érintó gond, automatizálni kéne.
- Lemeccseljük, hogy nem.

- Eltelik 1 hét, jelzi egy nyúzer, hogy nála gond van, desktop support tolja felénk, hogy nem tudja, mit kéne csinálni...

Na, ezért nem írok már step-by-step megoldókulcsot, azzal szenvedjen más, én inkább az új projektekbe igyekszem belemászni.

Közben megnéztem a cikket és ez biztonsági checklist-ről szól. Ilyen helyeken szerintem szokott azért lenni IT-ban is. Pl, hogy minek kell megfeleni, hogy egy release élesbe mehessen. De kérdés, hogy mennyi egyéb helyzetben lehetne ilyen chacklist jellegű dolgot alkalmazni. Sokkal inkább folyamat leírásokról van szó szerintem.

Amiről te beszélsz az a betanított munka, ez gyönyörűen automatizálható.

- "jaj, mi ez a hiba" -> le volt írva az is a troubleshootingban

a troubleshooting nem automatizálható :)

az ismétlődő dolgokban meg lehetnek hosszú átmeneti időszakok, pl.: automatizálás előtt áll vmi, azt le kéne dokumentálni, de ugye b*sznak leírni, ezzel anyagi kárt okozva a cégnek, hátráltatva az automatizálást.

Nem tudom, gondolkodtál-e már azon, vajon miért került be minden érettségibe szövegértéssel kapcsolatos feladat?

---
Science for fun...