Dobrý den, Habr! Jmenuji se Lesha a jsem systémový analytik jednoho z produktových týmů Alfa-Bank. Nyní vyvíjím novou online banku pro právnické osoby a fyzické osoby podnikatele.
A když jste analytik, zvláště 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 uvádí, jak by služba měla fungovat, ale vůbec to tak nefunguje? Čím to je, že specifikaci rozumí pouze dva lidé, z nichž jeden to napsal?
Dokumentaci však nelze ze zřejmých důvodů ignorovat. A abychom si usnadnili život, rozhodli jsme se zhodnotit kvalitu dokumentace. Jak přesně jsme to udělali a k jakým závěrům jsme došli, je níže.
Kvalita dokumentace
Aby se v textu neopakovalo „Nová internetová banka“ několik desítekkrát, napíšu NIB. Nyní máme více než desítku týmů, které pracují na rozvoji NIB pro podnikatele a právnické osoby. Navíc každý z nich buď vytváří vlastní dokumentaci pro novou službu nebo webovou aplikaci od začátku, nebo provádí změny v té stávající. Může být s tímto přístupem dokumentace v zásadě kvalitní?
A abychom určili kvalitu dokumentace, určili jsme tři hlavní charakteristiky.
- Musí být kompletní. Zní to jako kapitán, ale je důležité si to uvědomit. Měl by podrobně popsat všechny prvky implementovaného řešení.
- Musí být relevantní. Tedy odpovídat aktuální implementaci samotného řešení.
- Mělo by to být srozumitelné. Aby osoba, která jej používá, přesně pochopila, jak je řešení implementováno.
Shrnuto – kompletní, aktuální a srozumitelná dokumentace.
Опрос
Pro posouzení kvality dokumentace jsme se rozhodli vyzpovídat ty, kteří s ní přímo pracují: analytiky NIB. Respondenti měli hodnotit 10 výroků podle schématu „Na škále od 1 do 5 (naprosto nesouhlasím – zcela souhlasím).
Výroky odrážely charakteristiky kvalitativní dokumentace a názor zpracovatelů průzkumu na dokumenty NIB.
- Dokumentace k aplikacím NIB je aktuální a plně v souladu s jejich implementací.
- Implementace aplikací NIB je plně zdokumentována.
- Dokumentace pro aplikace NIB je nutná pouze pro funkční podporu.
- Dokumentace k žádostem NIB je aktuální v době jejich předložení k funkční podpoře.
- Vývojáři aplikací NIB používají dokumentaci, aby pochopili, co potřebují implementovat.
- Existuje dostatek dokumentace pro aplikace NIB, aby bylo možné pochopit, jak jsou implementovány.
- Ihned aktualizuji dokumentaci k projektům NIB, pokud jsou dokončeny (mým týmem).
- Vývojáři aplikací NIB kontrolují dokumentaci.
- Jasně rozumím tomu, jak připravit dokumentaci pro projekty NIB.
- Rozumím tomu, kdy psát/aktualizovat dokumentaci pro projekty NIB.
Je jasné, že pouhá odpověď „Od 1 do 5“ nemusí odhalit potřebné podrobnosti, takže člověk může zanechat komentář ke každé položce.
To vše jsme provedli prostřednictvím firemního Slacku – jednoduše jsme rozeslali pozvánku systémovým analytikům, aby se zúčastnili průzkumu. Bylo zde 15 analytiků (9 z Moskvy a 6 z Petrohradu). Po dokončení průzkumu jsme pro každý z 10 výroků vygenerovali průměrné skóre, které jsme následně standardizovali.
Tady je to, co se stalo.
Průzkum ukázal, že ačkoli se analytici přiklánějí k názoru, že implementace aplikací NIB je plně zdokumentována, nedávají jednoznačnou shodu (0.2). Jako konkrétní příklad uvedli, že řada databází a front ze stávajících řešení nebyla pokryta dokumentací. Vývojář je schopen říci analytikovi, že ne vše je zdokumentováno. Ale teze, že vývojáři revidují dokumentaci, také nezískala jednoznačnou podporu (0.33). To znamená, že riziko neúplného popisu implementovaných řešení zůstává.
Relevance je snazší – ačkoli opět neexistuje jasná shoda (0,13), analytici jsou stále nakloněni považovat dokumentaci za relevantní. Komentáře nám umožnily pochopit, že problémy s relevanci jsou častěji vepředu než uprostřed. O podpoře nám však nic nenapsali.
Pokud jde o to, zda sami analytici chápou, kdy je potřeba sepsat a aktualizovat dokumentaci, byla dohoda mnohem jednotnější (1,33), včetně jejího designu (1.07). Co zde bylo označeno za nepříjemnost, byl nedostatek jednotných pravidel pro vedení dokumentace. Aby tedy nezapnuli režim „Kdo jde do lesa, ten dostane dříví“, musí pracovat na příkladech existující dokumentace. Proto je užitečným přáním vytvořit standard pro správu dokumentů a vyvinout šablony pro jejich části.
Dokumentace k aplikacím NIB je aktuální v době odeslání k funkční podpoře (0.73). Je to pochopitelné, protože jedním z kritérií pro předložení projektu k funkční podpoře je aktuální dokumentace. Je také dostačující pochopit implementaci (0.67), i když někdy zůstávají otázky.
S čím ale respondenti nesouhlasili (zcela jednohlasně), bylo, že dokumentace k aplikacím NIB je v zásadě potřeba pouze pro funkční podporu (-1.53). Jako spotřebitelé dokumentace byli nejčastěji uváděni analytici. Zbytek týmu (vývojáři) - mnohem méně často. Navíc se analytici domnívají, že vývojáři nepoužívají dokumentaci k tomu, aby pochopili, co potřebují implementovat, i když ne jednomyslně (-0.06). To se mimochodem očekává také v podmínkách, kdy vývoj kódu a psaní dokumentace probíhají paralelně.
Jaký je konečný výsledek a proč tato čísla potřebujeme?
Abychom zlepšili kvalitu dokumentů, rozhodli jsme se udělat následující:
- Požádejte vývojáře, aby zkontroloval písemné dokumenty.
- Pokud je to možné, aktualizujte dokumentaci včas, zepředu.
- Vytvořte a přijměte standard pro dokumentaci projektů NIB, aby každý rychle pochopil, které prvky systému a jak přesně by měly být popsány. Vytvořte vhodné šablony.
To vše by mělo pomoci pozvednout kvalitu dokumentů na novou úroveň.
Alespoň v to doufám.
Zdroj: www.habr.com