Hei, Habr! Mitt navn er Lesha, jeg er systemanalytiker for et av Alfa-Banks produktteam. Nå utvikler jeg en ny nettbank for juridiske personer og enkeltentreprenører.
Og når du er analytiker, spesielt i en slik kanal, kommer du ingen vei uten dokumentasjon og tett arbeid med den. Og dokumentasjon er noe som alltid reiser mange spørsmål. Hvorfor er ikke nettapplikasjonen beskrevet? Hvorfor angir spesifikasjonen hvordan tjenesten skal fungere, men den fungerer ikke slik i det hele tatt? Hvorfor er det bare to personer, hvorav den ene skrev den, kan forstå spesifikasjonen?
Dokumentasjon kan imidlertid ikke ignoreres av åpenbare grunner. Og for å gjøre livet vårt enklere, bestemte vi oss for å evaluere kvaliteten på dokumentasjonen. Hvordan vi gjorde dette og hvilke konklusjoner vi kom til er under snittet.
Dokumentasjonskvalitet
For ikke å gjenta "Ny nettbank" flere dusin ganger i teksten, vil jeg skrive NIB. Nå har vi mer enn et dusin team som jobber med utviklingen av NIB for gründere og juridiske personer. Dessuten lager hver av dem enten sin egen dokumentasjon for en ny tjeneste eller webapplikasjon fra bunnen av, eller gjør endringer i den nåværende. Kan dokumentasjonen med denne tilnærmingen i prinsippet være av høy kvalitet?
Og for å bestemme kvaliteten på dokumentasjonen har vi identifisert tre hovedkjennetegn.
- Den må være komplett. Dette høres ganske kaptein-aktig ut, men det er viktig å merke seg. Den skal beskrive i detalj alle elementer i den implementerte løsningen.
- Det må være relevant. Det vil si tilsvarer dagens implementering av selve løsningen.
- Det bør være forståelig. Slik at personen som bruker det forstår nøyaktig hvordan løsningen er implementert.
For å oppsummere - komplett, oppdatert og forståelig dokumentasjon.
Опрос
For å vurdere kvaliteten på dokumentasjonen bestemte vi oss for å intervjue de som jobber direkte med den: NIB-analytikere. Respondentene ble bedt om å vurdere 10 påstander i henhold til skjemaet "På en skala fra 1 til 5 (helt uenig - helt enig)."
Uttalelsene reflekterte egenskapene til kvalitativ dokumentasjon og oppfatningen til undersøkelseskompilatorene angående NIB-dokumenter.
- Dokumentasjonen for NIB-applikasjonene er oppdatert og helt i samsvar med implementeringen.
- Implementeringen av NIB-applikasjoner er fullt dokumentert.
- Dokumentasjon for NIB-applikasjoner er kun nødvendig for funksjonell støtte.
- Dokumentasjon for NIB-søknader er aktuelt på tidspunktet for innsending for funksjonell støtte.
- NIB-applikasjonsutviklere bruker dokumentasjon for å forstå hva de trenger å implementere.
- Det er nok dokumentasjon til at NIB-applikasjonene forstår hvordan de implementeres.
- Jeg oppdaterer dokumentasjon på NIB-prosjekter umiddelbart hvis de er ferdigstilt (av teamet mitt).
- NIB applikasjonsutviklere gjennomgår dokumentasjon.
- Jeg har en klar forståelse av hvordan man utarbeider dokumentasjon for NIB-prosjekter.
- Jeg forstår når jeg skal skrive/oppdatere dokumentasjon for NIB-prosjekter.
Det er klart at bare å svare "Fra 1 til 5" kanskje ikke avslører de nødvendige detaljene, så en person kan legge igjen en kommentar til hvert element.
Vi gjorde alt dette gjennom bedriftens Slack - vi sendte ganske enkelt ut en invitasjon til systemanalytikere om å ta en undersøkelse. Det var 15 analytikere (9 fra Moskva og 6 fra St. Petersburg). Etter at undersøkelsen var fullført, genererte vi en gjennomsnittsscore for hver av de 10 påstandene, som vi deretter standardiserte.
Dette er hva som skjedde.
Undersøkelsen viste at selv om analytikere er tilbøyelige til å tro at implementeringen av NIB-applikasjoner er fullt dokumentert, gir de ikke entydig enighet (0.2). Som et konkret eksempel viste de til at en rekke databaser og køer fra eksisterende løsninger ikke var dekket av dokumentasjon. Utvikleren kan fortelle analytikeren at ikke alt er dokumentert. Men tesen om at utviklere gjennomgår dokumentasjon fikk heller ikke entydig støtte (0.33). Det vil si at risikoen for ufullstendig beskrivelse av implementerte løsninger består.
Relevans er lettere – selv om det igjen ikke er noen klar enighet (0,13), er analytikere fortsatt tilbøyelige til å vurdere dokumentasjonen som relevant. Kommentarene tillot oss å forstå at problemer med relevans oftere er foran enn i midten. Imidlertid skrev de ikke noe til oss om støtte.
Når det gjelder hvorvidt analytikerne selv forstår når det er nødvendig å skrive og oppdatere dokumentasjon, var avtalen mye mer enhetlig (1,33), inkludert utformingen (1.07). Det som her ble bemerket som en ulempe var mangelen på enhetlige regler for vedlikehold av dokumentasjon. Derfor, for ikke å slå på "Hvem går til skogen, hvem får ved"-modus, må de jobbe basert på eksempler på eksisterende dokumentasjon. Derfor er et nyttig ønske å lage en standard for dokumenthåndtering og utvikle maler for deres deler.
Dokumentasjon for NIB-søknader er aktuelt på innleveringstidspunktet for funksjonsstøtte (0.73). Dette er forståelig, fordi et av kriteriene for å sende inn et prosjekt for funksjonell støtte er oppdatert dokumentasjon. Det er også tilstrekkelig å forstå implementeringen (0.67), selv om noen ganger gjenstår spørsmål.
Men det respondentene ikke var enig i (ganske enstemmig) var at dokumentasjon for NIB-søknader i utgangspunktet kun er nødvendig for funksjonell støtte (-1.53). Analytikere ble oftest nevnt som forbrukere av dokumentasjon. Resten av teamet (utviklere) - mye sjeldnere. Dessuten mener analytikere at utviklere ikke bruker dokumentasjon for å forstå hva de trenger å implementere, men ikke enstemmig (-0.06). Dette forventes for øvrig også i forhold der kodeutvikling og dokumentasjonsskriving foregår parallelt.
Hva er bunnlinjen og hvorfor trenger vi disse tallene?
For å forbedre kvaliteten på dokumenter bestemte vi oss for å gjøre følgende:
- Be utvikleren om å gjennomgå skriftlige dokumenter.
- Hvis mulig, oppdater dokumentasjonen i tide, front først.
- Lag og ta i bruk en standard for å dokumentere NIB-prosjekter slik at alle raskt kan forstå hvilke systemelementer og hvordan nøyaktig skal beskrives. Vel, utvikle passende maler.
Alt dette skal bidra til å heve kvaliteten på dokumenter til et nytt nivå.
Jeg håper i hvert fall det.
Kilde: www.habr.com