Ahoj, Habre! Jmenuji se Lesha a jsem systémový analytik pro jeden z produktových týmů Alfa-Banky. Momentálně vyvíjím novou online banku pro firmy a živnostníky.
A když jste analytik, obzvlášť v takovém kanálu, bez dokumentace a úzké spolupráce s ní se nikam nedostanete. A dokumentace je něco, co vždy vyvolává spoustu otázek. Proč není webová aplikace popsána? Proč specifikace popisuje, jak by měla služba fungovat, ale vůbec to tak nefunguje? Proč specifikaci rozumí jen dva lidé, z nichž jeden ji napsal?
Ignorování dokumentace je však z pochopitelných důvodů nemožné. Pro usnadnění jsme se rozhodli provést posouzení kvality dokumentace. Níže uvádíme, jak jsme to provedli a naše závěry.
Kvalita dokumentace
Abych se vyhnul desítkám opakování termínu „Nová internetová banka“, budu používat termín „NIB“. V současné době máme přes tucet týmů, které pracují na vývoji NIB pro podnikatele a právnické osoby. Každý tým buď vytváří vlastní dokumentaci pro novou službu nebo webovou aplikaci od nuly, nebo provádí změny v té stávající. Lze tímto přístupem dosáhnout vysoce kvalitní dokumentace?
Pro určení kvality dokumentace jsme identifikovali tři hlavní charakteristiky.
- Musí být komplexní. Zní to poněkud ceremoniálně, ale je důležité si to uvědomit. Musí podrobně popisovat všechny prvky implementovaného řešení.
- Musí být aktuální, což znamená, že musí odpovídat aktuální implementaci samotného řešení.
- Musí být jasné, aby osoba, která jej používá, přesně chápala, jak je řešení implementováno.
Stručně řečeno: kompletní, aktuální a srozumitelná dokumentace.
Опрос
Abychom posoudili kvalitu dokumentace, rozhodli jsme se provést průzkum mezi těmi, kteří s ní přímo pracují: analytiky NIB. Respondenti byli požádáni, aby ohodnotili 10 tvrzení na stupnici od 1 do 5 (zcela nesouhlasím – zcela souhlasím).
Tato tvrzení odrážela charakteristiky kvalitní dokumentace a názory autorů průzkumu na dokumenty NIB.
- Dokumentace k aplikacím NIB je aktuální a plně odpovídá jejich implementaci.
- Implementace aplikací NIB je plně zdokumentována.
- Dokumentace k aplikacím NIB je potřeba pouze pro funkční podporu.
- Dokumentace k aplikacím NIB je aktuální v době jejich předložení k funkční podpoře.
- Vývojáři aplikací NIB používají dokumentaci k pochopení toho, co je třeba implementovat.
- Dokumentace k aplikacím NIB je dostatečná k pochopení jejich implementace.
- Dokumentaci k projektům NIB neprodleně aktualizuji v případě jejich revize (mým týmem).
- Vývojáři aplikací NIB kontrolují dokumentaci.
- Mám jasnou představu o tom, jak připravit dokumentaci pro projekty NIB.
- Rozumím, kdy psát/aktualizovat dokumentaci pro projekty NIB.
Je jasné, že pouhá odpověď „1 až 5“ nemusí odhalit potřebné podrobnosti, takže daná osoba může ke každé položce zanechat komentář.
To vše jsme provedli prostřednictvím firemního systému Slack – jednoduše jsme rozeslali pozvánku k průzkumu 15 systémovým analytikům (devíti z Moskvy a šesti z Petrohradu). Po dokončení průzkumu jsme pro každé z 10 tvrzení vygenerovali průměrné hodnocení, které jsme následně standardizovali.
Takhle se to stalo.
Průzkum ukázal, že ačkoliv se analytici přiklánějí k názoru, že implementace aplikací NIB je plně zdokumentována, nejsou s tím zcela souhlasní (0.2). Jako konkrétní příklad uvedli skutečnost, že několik databází a front v existujících řešeních nebylo pokryto dokumentací. Vývojář může analytika upozornit na to, že ne vše je zdokumentováno. Myšlenka, že vývojáři kontrolují dokumentaci, však také nezískala jednoznačnou podporu (0.33). To znamená, že riziko neúplných popisů implementovaných řešení přetrvává.
Relevance je o něco přímočařejší – i když stále neexistuje jasný konsenzus (0,13), analytici stále považují dokumentaci za aktuální. Komentáře ukázaly, že problémy s relevancí jsou častější na frontendu než ve střední části. O backendu jsme však nic neslyšeli.
Ohledně toho, zda analytici sami chápou, kdy psát a aktualizovat dokumentaci, panovala mnohem větší shoda (1,33), včetně jejího formátování (1.07). Jako nevýhoda byla zde označena absence jednotných pravidel pro vedení dokumentace. Aby se předešlo univerzálnímu přístupu, jsou analytici nuceni pracovat na základě existujících příkladů dokumentace. Užitečným návrhem je proto vytvořit standard pro správu dokumentů a pro jeho komponenty vyvinout šablony.
Dokumentace k aplikacím NIB je v době předložení funkční podpory aktuální (0.73). To je pochopitelné, protože jedním z kritérií projektu pro předložení funkční podpory je aktuální dokumentace. Je také dostatečná pro pochopení implementace (0.67), ačkoli někdy přetrvávají otázky.
Respondenti však nesouhlasili (spíše jednomyslně) s názorem, že dokumentace pro aplikace NIB je obecně potřebná pouze pro funkční podporu (-1.53). Analytici byli nejčastěji uváděni jako příjemci dokumentace, zatímco ostatní členové týmu (vývojáři) byli uváděni mnohem méně často. Analytici se dále domnívají, že vývojáři nepoužívají dokumentaci k pochopení toho, co potřebují implementovat, i když ne jednomyslně (-0.06). To se mimochodem očekává i v prostředí, kde se vývoj kódu a dokumentace píší paralelně.
Jaký je konečný výsledek a proč tato čísla potřebujeme?
Pro zlepšení kvality dokumentů jsme se rozhodli provést následující:
- Požádejte vývojáře o kontrolu písemných dokumentů.
- Pokud je to možné, aktualizujte dokumentaci včas, v první řadě tu úvodní.
- Vytvořit a přijmout standard pro dokumentaci projektů NIS, aby každý mohl rychle pochopit, které systémové prvky je třeba popsat a jak. Také vyvinout odpovídající šablony.
To vše by mělo pomoci pozvednout kvalitu dokumentů na novou úroveň.
Alespoň doufám.
Zdroj: www.habr.com
