Szia Habr! A nevem Lesha, rendszerelemző vagyok az Alfa-Bank egyik termékcsapatánál. Most egy új online bankot fejlesztek jogi személyek és egyéni vállalkozók számára.
És amikor elemző vagy, különösen egy ilyen csatornában, nem juthatsz el sehova dokumentáció és szoros munka nélkül. A dokumentáció pedig mindig sok kérdést vet fel. Miért nincs leírva a webalkalmazás? Miért jelzi a specifikáció a szolgáltatás működését, de egyáltalán nem így működik? Miért van az, hogy csak két ember érti a specifikációt, akik közül az egyik írta?
A dokumentációt azonban nyilvánvaló okokból nem lehet figyelmen kívül hagyni. Életünk megkönnyítése érdekében úgy döntöttünk, hogy értékeljük a dokumentáció minőségét. Hogy pontosan hogyan csináltuk ezt, és milyen következtetésekre jutottunk, az a vágás alatt van.
A dokumentáció minősége
Annak érdekében, hogy ne ismételje meg többször a szövegben az „Új Internet Bank” kifejezést, NIB-et írok. Jelenleg több mint egy tucat csapat dolgozik a NIB fejlesztésén vállalkozók és jogi személyek számára. Sőt, mindegyik vagy a semmiből létrehozza a saját dokumentációját egy új szolgáltatáshoz vagy webalkalmazáshoz, vagy módosítja a jelenlegit. Ezzel a megközelítéssel elvileg jó minőségű lehet a dokumentáció?
A dokumentáció minőségének meghatározásához pedig három fő jellemzőt azonosítottunk.
- Teljesnek kell lennie. Ez meglehetősen kapitánynak hangzik, de fontos megjegyezni. Részletesen le kell írnia a megvalósított megoldás minden elemét.
- Aktuálisnak kell lennie. Azaz megfelel magának a megoldás jelenlegi megvalósításának.
- Érthetőnek kell lennie. Hogy az azt használó személy pontosan megértse, hogyan valósítják meg a megoldást.
Összefoglalva - teljes, naprakész és érthető dokumentáció.
Опрос
A dokumentáció minőségének felmérése érdekében úgy döntöttünk, hogy megkérdezzük azokat, akik közvetlenül dolgoznak a dokumentációval: a NIB elemzőivel. A válaszadókat arra kérték, hogy értékeljenek 10 állítást az „1-től 5-ig terjedő skálán (teljes mértékben nem értek egyet - teljesen egyetértek)” séma szerint.
Az állítások tükrözték a kvalitatív dokumentáció sajátosságait és a felmérés készítőinek véleményét a NIB dokumentumokkal kapcsolatban.
- A NIB alkalmazások dokumentációja naprakész és teljes mértékben összhangban van a megvalósításukkal.
- A NIB alkalmazások megvalósítása teljes mértékben dokumentált.
- A NIB alkalmazások dokumentációja csak a funkcionális támogatáshoz szükséges.
- A NIB alkalmazások dokumentációja a funkcionális támogatásra való benyújtás időpontjában aktuális.
- A NIB alkalmazásfejlesztői a dokumentáció segítségével megértik, mit kell megvalósítaniuk.
- Elegendő dokumentáció áll rendelkezésre a NIB alkalmazások számára ahhoz, hogy megértsék, hogyan valósulnak meg.
- Azonnal frissítem a NIB-projektek dokumentációját, ha azokat véglegesítették (a csapatom).
- A NIB alkalmazásfejlesztői áttekintik a dokumentációt.
- Tisztán tudom, hogyan kell elkészíteni a NIB projektek dokumentációját.
- Megértem, mikor kell írni/frissíteni a NIB-projektek dokumentációját.
Nyilvánvaló, hogy az „1-től 5-ig” válaszadás nem feltétlenül fedi fel a szükséges részleteket, így egy személy megjegyzést fűzhet az egyes tételekhez.
Mindezt a vállalati Slacken keresztül tettük – egyszerűen kiküldtünk egy felkérést a rendszerelemzőknek, hogy végezzenek felmérést. 15 elemző volt (9 moszkvai és 6 szentpétervári). A felmérés befejezése után a 10 állítás mindegyikére átlagpontszámot generáltunk, amelyet azután standardizáltunk.
Íme, mi történt.
A felmérés kimutatta, hogy bár az elemzők hajlamosak azt hinni, hogy a NIB-alkalmazások megvalósítása teljes mértékben dokumentált, nem adnak egyértelmű egyetértést (0.2). Konkrét példaként felhívták a figyelmet arra, hogy számos adatbázist és a meglévő megoldásokból származó várólista nem terjed ki a dokumentációra. A fejlesztő meg tudja mondani az elemzőnek, hogy nincs minden dokumentálva. De az a tézis, hogy a fejlesztők átnézik a dokumentációt, szintén nem kapott egyértelmű támogatást (0.33). Vagyis fennáll annak a veszélye, hogy a megvalósított megoldások leírása nem teljes.
A relevancia könnyebb – bár ismét nincs egyértelmű egyetértés (0,13), az elemzők továbbra is hajlamosak a dokumentációt relevánsnak tekinteni. A megjegyzésekből megértettük, hogy a relevanciával kapcsolatos problémák gyakrabban vannak elöl, mint középen. A támogatásról azonban nem írtak nekünk semmit.
Ami azt illeti, hogy maguk az elemzők is értik-e, hogy mikor kell dokumentációt írni és frissíteni, a megállapodás sokkal egységesebb volt (1,33), beleértve a tervezést is (1.07). Amit itt kellemetlenségként jegyeztek meg, az az egységes dokumentáció-vezetési szabályok hiánya. Ezért, hogy ne kapcsolják be a „Ki megy az erdőbe, ki kap tűzifát” üzemmódot, a meglévő dokumentáció példái alapján kell dolgozniuk. Ezért hasznos kívánság egy dokumentumkezelési szabvány létrehozása és sablonok kidolgozása a részeikhez.
A NIB alkalmazások dokumentációja a funkcionális támogatás benyújtásának időpontjában aktuális (0.73). Ez érthető, mert a funkcionális támogatásra benyújtott projekt egyik feltétele a naprakész dokumentáció. A megvalósítás megértése is elegendő (0.67), bár néha kérdések maradnak.
Amivel azonban a válaszadók nem értettek egyet (meglehetősen egyöntetűen), az az, hogy a NIB alkalmazásokhoz elvileg csak a funkcionális támogatáshoz kell dokumentáció (-1.53). Leggyakrabban az elemzőket említették a dokumentáció fogyasztóiként. A csapat többi tagja (fejlesztők) - sokkal ritkábban. Sőt, az elemzők úgy vélik, hogy a fejlesztők nem használnak dokumentációt annak megértéséhez, hogy mit kell megvalósítaniuk, bár nem egyhangúan (-0.06). Ez egyébként olyan körülmények között is elvárható, ahol párhuzamosan zajlik a kódfejlesztés és a dokumentációírás.
Mi a lényeg, és miért van szükségünk ezekre a számokra?
A dokumentumok minőségének javítása érdekében a következők mellett döntöttünk:
- Kérje meg a fejlesztőt, hogy tekintse át az írásos dokumentumokat.
- Ha lehetséges, időben frissítse a dokumentációt, először.
- Hozzon létre és fogadjon el egy szabványt a NIB projektek dokumentálására, hogy mindenki gyorsan megértse, mely rendszerelemeket és hogyan kell pontosan leírni. Nos, dolgozzon ki megfelelő sablonokat.
Mindez hozzájárulhat a dokumentumok minőségének új szintre emeléséhez.
Legalábbis remélem.
Forrás: will.com