Hej, Habr! Mit navn er Lesha, jeg er systemanalytiker for et af Alfa-Banks produktteams. Nu er jeg ved at udvikle en ny netbank til juridiske enheder og individuelle iværksættere.
Og når man er analytiker, især i sådan en kanal, kan man ikke komme nogen vegne uden dokumentation og tæt arbejde med det. Og dokumentation er noget, der altid rejser mange spørgsmål. Hvorfor er webapplikationen ikke beskrevet? Hvorfor angiver specifikationen, hvordan tjenesten skal fungere, men sådan fungerer det slet ikke? Hvorfor er det kun to personer, hvoraf den ene har skrevet den, kan forstå specifikationen?
Dokumentation kan dog ikke ignoreres af indlysende årsager. Og for at gøre vores liv lettere, besluttede vi at evaluere kvaliteten af dokumentationen. Hvordan vi præcist gjorde dette, og hvilke konklusioner vi kom til, er under skæringen.
Dokumentationskvalitet
For ikke at gentage "Ny internetbank" flere dusin gange i teksten, vil jeg skrive NIB. Nu har vi mere end et dusin teams, der arbejder på udviklingen af NIB for iværksættere og juridiske enheder. Desuden opretter hver af dem enten sin egen dokumentation for en ny tjeneste eller webapplikation fra bunden, eller foretager ændringer i den nuværende. Kan dokumentationen med denne tilgang i princippet være af høj kvalitet?
Og for at bestemme kvaliteten af dokumentationen har vi identificeret tre hovedkarakteristika.
- Det skal være komplet. Det lyder ret kaptajn-agtigt, men det er vigtigt at bemærke. Den skal i detaljer beskrive alle elementer i den implementerede løsning.
- Det skal være aktuelt. Det vil sige svarer til den aktuelle implementering af selve løsningen.
- Det burde være forståeligt. Så den person, der bruger det, forstår præcis, hvordan løsningen implementeres.
For at opsummere - komplet, opdateret og forståelig dokumentation.
Опрос
For at vurdere kvaliteten af dokumentationen besluttede vi at interviewe dem, der arbejder direkte med den: NIB-analytikere. Respondenterne blev bedt om at vurdere 10 udsagn i henhold til skemaet "På en skala fra 1 til 5 (helt uenig - helt enig)."
Udsagnene afspejlede karakteristikaene ved kvalitativ dokumentation og undersøgelseskompilatorernes mening om NIB-dokumenter.
- Dokumentationen for NIB-applikationerne er opdateret og fuldt ud i overensstemmelse med deres implementering.
- Implementeringen af NIB-applikationer er fuldt dokumenteret.
- Dokumentation for NIB-applikationer er kun nødvendig for funktionel support.
- Dokumentation for NIB-ansøgninger er aktuel på tidspunktet for deres indsendelse til funktionel support.
- NIB applikationsudviklere bruger dokumentation til at forstå, hvad de skal implementere.
- Der er dokumentation nok til, at NIB-applikationerne kan forstå, hvordan de implementeres.
- Jeg opdaterer omgående dokumentation om NIB-projekter, hvis de er afsluttet (af mit team).
- NIB applikationsudviklere gennemgår dokumentation.
- Jeg har en klar forståelse af, hvordan man udarbejder dokumentation til NIB-projekter.
- Jeg forstår, hvornår jeg skal skrive/opdatere dokumentation for NIB-projekter.
Det er klart, at blot at svare "Fra 1 til 5" måske ikke afslører de nødvendige detaljer, så en person kan efterlade en kommentar til hvert element.
Vi gjorde alt dette gennem virksomhedens Slack - vi sendte simpelthen en invitation ud til systemanalytikere om at deltage i en undersøgelse. Der var 15 analytikere (9 fra Moskva og 6 fra St. Petersborg). Efter undersøgelsen var gennemført, genererede vi en gennemsnitlig score for hver af de 10 udsagn, som vi derefter standardiserede.
Dette er, hvad der skete.
Undersøgelsen viste, at selvom analytikere er tilbøjelige til at tro, at implementeringen af NIB-applikationer er fuldt dokumenteret, giver de ikke entydig enighed (0.2). Som et konkret eksempel pegede de på, at en række databaser og køer fra eksisterende løsninger ikke var dækket af dokumentation. Udvikleren er i stand til at fortælle analytikeren, at ikke alt er dokumenteret. Men tesen om, at udviklere gennemgår dokumentation, fik heller ikke entydig støtte (0.33). Det vil sige, at risikoen for ufuldstændig beskrivelse af implementerede løsninger forbliver.
Relevans er nemmere - selvom der igen ikke er en klar enighed (0,13), er analytikere stadig tilbøjelige til at betragte dokumentationen som relevant. Kommentarerne gjorde det muligt for os at forstå, at problemer med relevans oftere er foran end i midten. De skrev dog ikke noget til os om opbakning.
Med hensyn til hvorvidt analytikerne selv forstår, hvornår det er nødvendigt at skrive og opdatere dokumentation, var aftalen meget mere ensartet (1,33), inklusive dens udformning (1.07). Det, der her blev noteret som en ulempe, var manglen på ensartede regler for vedligeholdelse af dokumentation. For ikke at slå "Hvem går i skoven, hvem får brænde" til, skal de derfor arbejde ud fra eksempler på eksisterende dokumentation. Derfor er et nyttigt ønske at skabe en standard for dokumenthåndtering og udvikle skabeloner til deres dele.
Dokumentation for NIB-ansøgninger er aktuel på tidspunktet for indsendelse til funktionel support (0.73). Det er forståeligt, for et af kriterierne for at indsende et projekt til funktionel støtte er opdateret dokumentation. Det er også tilstrækkeligt at forstå implementeringen (0.67), selvom der nogle gange er spørgsmål.
Men hvad respondenterne ikke var enige i (helt enstemmigt) var, at dokumentation for NIB-ansøgninger i princippet kun er nødvendig for funktionel støtte (-1.53). Analytikere blev oftest nævnt som forbrugere af dokumentation. Resten af holdet (udviklere) - meget sjældnere. Desuden mener analytikere, at udviklere ikke bruger dokumentation til at forstå, hvad de skal implementere, dog ikke enstemmigt (-0.06). Dette forventes i øvrigt også i forhold, hvor kodeudvikling og dokumentationsskrivning foregår sideløbende.
Hvad er bundlinjen, og hvorfor har vi brug for disse tal?
For at forbedre kvaliteten af dokumenter besluttede vi at gøre følgende:
- Bed udvikleren om at gennemgå skriftlige dokumenter.
- Hvis det er muligt, skal du opdatere dokumentationen rettidigt, front først.
- Skab og adopter en standard for dokumentation af NIB-projekter, så alle hurtigt kan forstå, hvilke systemelementer og hvordan præcist skal beskrives. Nå, udvikle passende skabeloner.
Alt dette skulle være med til at løfte kvaliteten af dokumenter til et nyt niveau.
Det håber jeg i hvert fald.
Kilde: www.habr.com