Ahoj Habr! Volám sa Lesha a som systémový analytik jedného z produktových tímov Alfa-Bank. Teraz vyvíjam novú online banku pre právnické osoby a individuálnych podnikateľov.
A keď ste analytik, najmä v takomto kanáli, bez dokumentácie a úzkej spolupráce s ňou sa nikam nedostanete. A dokumentácia je niečo, čo vždy vyvoláva množstvo otázok. Prečo nie je popísaná webová aplikácia? Prečo špecifikácia naznačuje, ako by služba mala fungovať, ale vôbec to tak nefunguje? Čím to je, že špecifikácii rozumejú len dvaja ľudia, z ktorých jeden to napísal?
Dokumentáciu však z pochopiteľných dôvodov nemožno ignorovať. A aby sme si uľahčili život, rozhodli sme sa zhodnotiť kvalitu dokumentácie. Ako presne sme to urobili a k akým záverom sme dospeli, je nižšie.
Kvalita dokumentácie
Aby sa v texte neopakovalo niekoľko desiatok krát „Nová internetová banka“, napíšem NIB. Teraz máme viac ako tucet tímov, ktoré pracujú na rozvoji NIB pre podnikateľov a právnické osoby. Každý z nich si navyše buď vytvorí vlastnú dokumentáciu pre novú službu alebo webovú aplikáciu od začiatku, alebo vykoná zmeny v tej aktuálnej. Môže byť pri tomto prístupe dokumentácia v zásade kvalitná?
A na určenie kvality dokumentácie sme identifikovali tri hlavné charakteristiky.
- Musí byť kompletný. Znie to dosť kapitánsky, ale je dôležité si to uvedomiť. Mal by podrobne popísať všetky prvky implementovaného riešenia.
- Musí to byť aktuálne. Teda zodpovedajú aktuálnej implementácii samotného riešenia.
- Malo by to byť zrozumiteľné. Aby osoba, ktorá ho používa, presne pochopila, ako sa riešenie implementuje.
Suma sumárum – kompletná, aktuálna a zrozumiteľná dokumentácia.
Опрос
Na posúdenie kvality dokumentácie sme sa rozhodli urobiť rozhovor s tými, ktorí s ňou priamo pracujú: s analytikmi NIB. Respondenti mali ohodnotiť 10 výrokov podľa schémy „Na škále od 1 do 5 (úplne nesúhlasím – úplne súhlasím).
Výroky odrážali charakteristiky kvalitatívnej dokumentácie a názor spracovateľov prieskumu k dokumentom NIB.
- Dokumentácia k aplikáciám NIB je aktuálna a plne v súlade s ich implementáciou.
- Implementácia aplikácií NIB je plne zdokumentovaná.
- Dokumentácia pre aplikácie NIB je potrebná len pre funkčnú podporu.
- Dokumentácia k žiadostiam NIB je aktuálna v čase ich predloženia na funkčnú podporu.
- Vývojári aplikácií NIB používajú dokumentáciu, aby pochopili, čo potrebujú implementovať.
- Existuje dostatok dokumentácie pre aplikácie NIB, aby bolo možné pochopiť, ako sú implementované.
- Okamžite aktualizujem dokumentáciu o projektoch NIB, ak sú dokončené (môj tím).
- Vývojári aplikácií NIB kontrolujú dokumentáciu.
- Jasne rozumiem tomu, ako pripraviť dokumentáciu pre projekty NIB.
- Rozumiem, kedy treba písať/aktualizovať dokumentáciu pre projekty NIB.
Je jasné, že jednoduchá odpoveď „Od 1 do 5“ nemusí odhaliť potrebné podrobnosti, takže osoba môže zanechať komentár ku každej položke.
To všetko sme urobili cez firemný Slack – jednoducho sme rozoslali pozvánku systémovým analytikom, aby sa zúčastnili prieskumu. Bolo tam 15 analytikov (9 z Moskvy a 6 z Petrohradu). Po dokončení prieskumu sme pre každý z 10 výrokov vygenerovali priemerné skóre, ktoré sme následne štandardizovali.
Toto sa stalo.
Prieskum ukázal, že hoci sa analytici prikláňajú k názoru, že implementácia aplikácií NIB je plne zdokumentovaná, neposkytujú jednoznačný súhlas (0.2). Ako konkrétny príklad uviedli, že na množstvo databáz a front z existujúcich riešení sa nevzťahovala dokumentácia. Vývojár je schopný povedať analytikovi, že nie všetko je zdokumentované. Jednoznačnú podporu však nezískala ani téza, že vývojári kontrolujú dokumentáciu (0.33). To znamená, že riziko neúplného popisu implementovaných riešení zostáva.
Relevancia je jednoduchšia – aj keď opäť neexistuje jasná zhoda (0,13), analytici sú stále naklonení považovať dokumentáciu za relevantnú. Komentáre nám umožnili pochopiť, že problémy s relevantnosťou sú častejšie vpredu ako v strede. O podpore nám však nič nenapísali.
Pokiaľ ide o to, či samotní analytici rozumejú, kedy je potrebné písať a aktualizovať dokumentáciu, dohoda bola oveľa jednotnejšia (1,33), vrátane jej dizajnu (1.07). To, čo sa tu označilo za nepríjemnosť, bol nedostatok jednotných pravidiel na vedenie dokumentácie. Preto, aby nezapli režim „Kto ide do lesa, ten dostane drevo“, musia pracovať na príkladoch existujúcej dokumentácie. Preto je užitočné vytvoriť štandard pre správu dokumentov a vytvoriť šablóny pre ich časti.
Dokumentácia k žiadostiam NIB je aktuálna v čase predloženia na funkčnú podporu (0.73). Je to pochopiteľné, pretože jedným z kritérií na predloženie projektu na funkčné zabezpečenie je aktuálnosť dokumentácie. Postačí aj pochopenie implementácie (0.67), aj keď niekedy zostávajú otázky.
S čím však respondenti nesúhlasili (celkom jednomyseľne), že dokumentácia k aplikáciám NIB je v zásade potrebná len na funkčnú podporu (-1.53). Ako spotrebitelia dokumentácie boli najčastejšie uvádzaní analytici. Zvyšok tímu (vývojári) - oveľa menej často. Okrem toho sa analytici domnievajú, že vývojári nepoužívajú dokumentáciu na pochopenie toho, čo potrebujú implementovať, aj keď nie jednomyseľne (-0.06). To sa mimochodom očakáva aj v podmienkach, kde vývoj kódu a písanie dokumentácie prebieha paralelne.
Aký je základ a prečo potrebujeme tieto čísla?
Na zlepšenie kvality dokumentov sme sa rozhodli urobiť nasledovné:
- Požiadajte vývojára, aby skontroloval písomné dokumenty.
- Ak je to možné, aktualizujte dokumentáciu včas, vopred.
- Vytvorte a prijmite štandard pre dokumentáciu projektov NIB, aby každý mohol rýchlo pochopiť, ktoré prvky systému a ako presne by mali byť opísané. No, vytvorte vhodné šablóny.
To všetko by malo pomôcť pozdvihnúť kvalitu dokumentov na novú úroveň.
Aspoň dúfam.
Zdroj: hab.com