Hej, Habr! Jag heter Lesha, jag är systemanalytiker för ett av Alfa-Banks produktteam. Nu utvecklar jag en ny nätbank för juridiska personer och enskilda företagare.
Och när du är analytiker, särskilt i en sådan kanal, kan du inte komma någonstans utan dokumentation och nära arbete med den. Och dokumentation är något som alltid väcker många frågor. Varför beskrivs inte webbapplikationen? Varför anger specifikationen hur tjänsten ska fungera, men den fungerar inte alls så? Varför är det bara två personer, varav en skrev det, som kan förstå specifikationen?
Dokumentation kan dock inte ignoreras av uppenbara skäl. Och för att göra vårt liv enklare bestämde vi oss för att utvärdera kvaliteten på dokumentationen. Hur vi exakt gjorde detta och vilka slutsatser vi kom fram till är under snittet.
Dokumentationskvalitet
För att inte upprepa "Ny Internetbank" flera dussin gånger i texten kommer jag att skriva NIB. Nu har vi mer än ett dussin team som arbetar med utvecklingen av NIB för entreprenörer och juridiska personer. Dessutom skapar var och en av dem antingen sin egen dokumentation för en ny tjänst eller webbapplikation från grunden, eller gör ändringar i den nuvarande. Kan dokumentationen med detta synsätt i princip hålla hög kvalitet?
Och för att fastställa kvaliteten på dokumentationen har vi identifierat tre huvudegenskaper.
- Den måste vara komplett. Det här låter ganska kaptenslikt, men det är viktigt att notera. Den ska i detalj beskriva alla delar av den implementerade lösningen.
- Den måste vara aktuell. Det vill säga motsvarar den nuvarande implementeringen av själva lösningen.
- Det borde vara begripligt. Så att personen som använder den förstår exakt hur lösningen implementeras.
För att sammanfatta - komplett, uppdaterad och begriplig dokumentation.
Interview
För att bedöma kvaliteten på dokumentationen bestämde vi oss för att intervjua de som direkt arbetar med den: NIB-analytiker. Respondenterna ombads att utvärdera 10 påståenden enligt schemat "På en skala från 1 till 5 (inte instämmer helt - håller helt med)."
Utlåtandena återspeglade egenskaperna hos kvalitativ dokumentation och undersökningskompilatorernas åsikter om NIB-dokument.
- Dokumentationen för NIB-applikationerna är uppdaterad och helt överensstämmande med deras implementering.
- Implementeringen av NIB-applikationer är fullständigt dokumenterad.
- Dokumentation för NIB-applikationer behövs endast för funktionellt stöd.
- Dokumentation för NIB-ansökningar är aktuell vid tidpunkten för inlämning av funktionsstöd.
- NIB-applikationsutvecklare använder dokumentation för att förstå vad de behöver implementera.
- Det finns tillräckligt med dokumentation för att NIB-applikationerna ska förstå hur de implementeras.
- Jag uppdaterar omgående dokumentation om NIB-projekt om de slutförs (av mitt team).
- NIB applikationsutvecklare granskar dokumentation.
- Jag har en klar förståelse för hur man förbereder dokumentation för NIB-projekt.
- Jag förstår när jag ska skriva/uppdatera dokumentation för NIB-projekt.
Det är uppenbart att bara att svara "Från 1 till 5" kanske inte avslöjar de nödvändiga detaljerna, så en person kan lämna en kommentar om varje objekt.
Vi gjorde allt detta genom företagets Slack - vi skickade helt enkelt ut en inbjudan till systemanalytiker att göra en undersökning. Det fanns 15 analytiker (9 från Moskva och 6 från St. Petersburg). Efter att undersökningen slutförts genererade vi ett medelpoäng för vart och ett av de 10 påståendena, som vi sedan standardiserade.
Här är vad som hände.
Undersökningen visade att även om analytiker är benägna att tro att implementeringen av NIB-applikationer är fullt dokumenterade, ger de inte en entydig överenskommelse (0.2). Som ett konkret exempel påpekade de att ett antal databaser och köer från befintliga lösningar inte omfattades av dokumentation. Utvecklaren kan berätta för analytikern att allt inte är dokumenterat. Men tesen att utvecklare granskar dokumentation fick inte heller entydigt stöd (0.33). Det vill säga att risken för ofullständig beskrivning av implementerade lösningar kvarstår.
Relevans är lättare - även om det återigen inte finns någon tydlig överenskommelse (0,13), är analytiker fortfarande benägna att anse dokumentationen som relevant. Kommentarerna gjorde det möjligt för oss att förstå att problem med relevans oftare finns längst fram än i mitten. Men de skrev inget till oss om stöd.
När det gäller om analytikerna själva förstår när det är nödvändigt att skriva och uppdatera dokumentation var avtalet mycket mer enhetligt (1,33), inklusive dess utformning (1.07). Vad som här noterades som en olägenhet var avsaknaden av enhetliga regler för att föra dokumentation. Därför, för att inte aktivera läget "Vem går till skogen, vem får ved" måste de arbeta utifrån exempel på befintlig dokumentation. Därför är en användbar önskan att skapa en standard för dokumenthantering och utveckla mallar för deras delar.
Dokumentation för NIB-ansökningar är aktuell vid inlämningstillfället för funktionsstöd (0.73). Detta är förståeligt, eftersom ett av kriterierna för att lämna in ett projekt för funktionsstöd är uppdaterad dokumentation. Det räcker också för att förstå implementeringen (0.67), även om det ibland återstår frågor.
Men vad respondenterna inte höll med om (ganska enhälligt) var att dokumentation för NIB-ansökningar i princip bara behövs för funktionsstöd (-1.53). Analytiker nämndes oftast som konsumenter av dokumentation. Resten av teamet (utvecklare) - mycket mer sällan. Dessutom tror analytiker att utvecklare inte använder dokumentation för att förstå vad de behöver implementera, men inte enhälligt (-0.06). Detta förväntas för övrigt även under förhållanden där kodutveckling och dokumentationsskrivning pågår parallellt.
Vad är slutsatsen och varför behöver vi dessa siffror?
För att förbättra kvaliteten på dokumenten bestämde vi oss för att göra följande:
- Be utvecklaren att granska skriftliga dokument.
- Uppdatera om möjligt dokumentationen i tid, fram först.
- Skapa och anta en standard för att dokumentera NIB-projekt så att alla snabbt kan förstå vilka systemelement och hur exakt som ska beskrivas. Tja, utveckla lämpliga mallar.
Allt detta bör bidra till att höja kvaliteten på dokument till en ny nivå.
Jag hoppas det åtminstone.
Källa: will.com