Hei, Habr! Nimeni on Lesha, olen järjestelmäanalyytikko yhdessä Alfa-Bankin tuotetiimistä. Nyt olen kehittämässä uutta verkkopankkia juridisille henkilöille ja yksittäisille yrittäjille.
Ja kun olet analyytikko, varsinkin sellaisessa kanavassa, et pääse minnekään ilman dokumentaatiota ja läheistä yhteistyötä sen kanssa. Ja dokumentointi herättää aina paljon kysymyksiä. Miksi verkkosovellusta ei kuvata? Miksi spesifikaatio kertoo, miten palvelun pitäisi toimia, mutta se ei toimi ollenkaan niin? Miksi vain kaksi henkilöä, joista toinen kirjoitti sen, voi ymmärtää eritelmän?
Asiakirjoja ei kuitenkaan voida jättää huomiotta ilmeisistä syistä. Ja helpottaaksemme elämäämme päätimme arvioida dokumentaation laatua. Kuinka tarkasti teimme tämän ja mihin johtopäätöksiin teimme, on leikkauksen alapuolella.
Dokumentaation laatu
Jotta en toistaisi "Uutta Internet-pankkia" useita kymmeniä kertoja tekstissä, kirjoitan NIB. Nyt meillä on yli tusina työryhmää yrittäjille ja juridisille henkilöille suunnatun NIB:n kehittämisen parissa. Lisäksi jokainen heistä joko luo alusta alkaen oman dokumentaation uudelle palvelulle tai verkkosovellukselle tai tekee muutoksia nykyiseen. Voiko dokumentaatio olla periaatteessa laadukasta tällä lähestymistavalla?
Ja dokumentaation laadun määrittämiseksi olemme tunnistaneet kolme pääpiirrettä.
- Sen on oltava täydellinen. Tämä kuulostaa melko kapteenilta, mutta on tärkeää huomata. Siinä tulee kuvata yksityiskohtaisesti kaikki toteutetun ratkaisun elementit.
- Sen on oltava relevanttia. Eli vastaa itse ratkaisun nykyistä toteutusta.
- Sen pitäisi olla ymmärrettävää. Jotta sitä käyttävä henkilö ymmärtää tarkalleen kuinka ratkaisu toteutetaan.
Yhteenvetona - täydellinen, ajantasainen ja ymmärrettävä dokumentaatio.
Опрос
Dokumentaation laadun arvioimiseksi päätimme haastatella niitä, jotka työskentelevät suoraan sen parissa: NIB-analyytikot. Vastaajia pyydettiin arvioimaan 10 väitettä asteikolla 1-5 (täysin eri mieltä - täysin samaa mieltä).
Lausunnot heijastivat laadullisen dokumentaation ominaispiirteitä ja kyselyn laatijien mielipidettä NIB-asiakirjoista.
- NIB-sovellusten dokumentaatio on ajan tasalla ja täysin yhdenmukainen niiden toteutuksen kanssa.
- NIB-sovellusten toteutus on täysin dokumentoitu.
- NIB-sovellusten dokumentaatiota tarvitaan vain toiminnallista tukea varten.
- NIB-sovellusten dokumentaatio on ajan tasalla, kun ne lähetetään toiminnallista tukea varten.
- NIB-sovelluskehittäjät käyttävät dokumentaatiota ymmärtääkseen, mitä heidän on toteutettava.
- NIB-sovelluksille on riittävästi dokumentaatiota ymmärtääkseen, kuinka ne on toteutettu.
- Päivitän viipymättä NIB-projektien dokumentaatiot, jos ne on viimeistelty (tiimini toimesta).
- NIB-sovelluskehittäjät tarkistavat asiakirjat.
- Minulla on selkeä käsitys siitä, kuinka NIB-hankkeiden dokumentaatio laaditaan.
- Ymmärrän, milloin NIB-projektien dokumentaatio tulee kirjoittaa/päivittää.
On selvää, että pelkkä vastaus "1-5" ei välttämättä paljasta tarvittavia yksityiskohtia, joten henkilö voi jättää kommentin jokaiseen kohtaan.
Teimme kaiken tämän yrityksen Slackin kautta - lähetimme yksinkertaisesti kutsun järjestelmäanalyytikoille osallistua kyselyyn. Analyytikoita oli 15 (9 Moskovasta ja 6 Pietarista). Kun kysely oli valmis, loimme jokaiselle 10 väitteelle keskimääräisen pistemäärän, jonka sitten standardoimme.
Tässä on mitä tapahtui.
Tutkimus osoitti, että vaikka analyytikot ovat taipuvaisia uskomaan, että NIB-sovellusten toteutus on täysin dokumentoitu, he eivät anna yksiselitteistä hyväksyntää (0.2). Erityisenä esimerkkinä he toivat esiin, että monet tietokannat ja jonot olemassa olevista ratkaisuista eivät kuuluneet dokumentaatioon. Kehittäjä voi kertoa analyytikolle, että kaikkea ei ole dokumentoitu. Mutta väitöskirja, jonka mukaan kehittäjät tarkastelevat dokumentaatiota, ei myöskään saanut yksiselitteistä tukea (0.33). Toisin sanoen riski toteutuneiden ratkaisujen epätäydellisestä kuvauksesta säilyy.
Relevanssi on helpompaa - vaikka selkeää yksimielisyyttä ei taaskaan ole (0,13), analyytikot ovat edelleen taipuvaisia pitämään dokumentaatiota relevanttina. Kommenttien avulla ymmärsimme, että osuvuusongelmat ovat useammin edessä kuin keskellä. He eivät kuitenkaan kirjoittaneet meille mitään tukemisesta.
Mitä tulee siihen, ymmärtävätkö analyytikot itse, milloin on tarpeen kirjoittaa ja päivittää dokumentaatiota, sopimus oli paljon yhtenäisempi (1,33), suunnittelu mukaan lukien (1.07). Haittana tässä todettiin asiakirjojen ylläpitoa koskevien yhtenäisten sääntöjen puuttuminen. Siksi, jotta "Kuka menee metsään, kuka saa polttopuita" -tilaa ei oteta käyttöön, heidän on työskenneltävä olemassa olevan dokumentaation esimerkkien perusteella. Tästä syystä hyödyllinen toive on luoda standardi dokumenttien hallintaan ja kehittää malleja niiden osille.
NIB-sovellusten dokumentaatio on ajan tasalla toiminnallisen tuen jättöhetkellä (0.73). Tämä on ymmärrettävää, sillä yksi kriteereistä hankkeen toimittamiseen toiminnalliseen tukeen on ajantasainen dokumentaatio. Riittää myös toteutuksen ymmärtäminen (0.67), vaikka joskus kysymyksiä jää.
Mutta mitä vastaajat eivät olleet samaa mieltä (melko yksimielisesti), oli se, että NIB-sovellusten dokumentaatiota tarvitaan periaatteessa vain toiminnalliseen tukeen (-1.53). Analyytikot mainittiin useimmiten dokumentaation kuluttajina. Muu tiimi (kehittäjät) - paljon harvemmin. Lisäksi analyytikot uskovat, että kehittäjät eivät käytä dokumentaatiota ymmärtääkseen, mitä heidän on toteutettava, vaikkakaan ei yksimielisesti (-0.06). Tämä on muuten odotettavissa myös olosuhteissa, joissa koodin kehitys ja dokumentaation kirjoittaminen etenevät rinnakkain.
Mikä on lopputulos ja miksi tarvitsemme näitä numeroita?
Asiakirjojen laadun parantamiseksi päätimme tehdä seuraavaa:
- Pyydä kehittäjää tarkistamaan kirjalliset asiakirjat.
- Jos mahdollista, päivitä dokumentaatio ajoissa, etusijalla.
- Luo ja ota käyttöön standardi NIB-projektien dokumentoimiseksi, jotta kaikki ymmärtävät nopeasti, mitkä järjestelmän elementit ja miten tarkasti pitäisi kuvata. No, kehitä sopivat mallit.
Kaiken tämän pitäisi auttaa nostamaan asiakirjojen laatua uudelle tasolle.
Ainakin toivon niin.
Lähde: will.com