Сәлем, Хабр! Менің атым Леша, мен Альфа-Банктің өнім топтарының бірінің жүйелік талдаушысымын. Қазір мен заңды тұлғалар мен жеке кәсіпкерлер үшін жаңа онлайн-банк жасап жатырмын.
Ал сіз аналитик болған кезде, әсіресе мұндай арнада құжатсыз және онымен тығыз жұмыссыз ешқайда жете алмайсыз. Ал құжаттама әрқашан көп сұрақ тудыратын нәрсе. Неліктен веб-бағдарлама сипатталмаған? Неліктен спецификация қызметтің қалай жұмыс істейтінін көрсетеді, бірақ ол мүлде жұмыс істемейді? Неліктен спецификацияны бір жазған екі адам ғана түсінеді?
Дегенмен, белгілі себептермен құжаттаманы елемеу мүмкін емес. Ал өмірімізді жеңілдету үшін біз құжаттаманың сапасын бағалауды жөн көрдік. Біз мұны қалай орындадық және қандай қорытындыға келдік, қысқаша төменде.
Құжаттама сапасы
Мәтінде «Жаңа Интернет-банк» бірнеше ондаған рет қайталанбау үшін мен NIB жазамын. Қазір бізде кәсіпкерлер мен заңды тұлғаларға арналған NIB әзірлеумен айналысатын оннан астам командалар бар. Сонымен қатар, олардың әрқайсысы нөлден бастап жаңа қызмет немесе веб-қосымша үшін жеке құжаттаманы жасайды немесе ағымдағыға өзгерістер енгізеді. Бұл тәсілмен құжаттама негізінен жоғары сапалы болуы мүмкін бе?
Ал құжаттаманың сапасын анықтау үшін біз негізгі үш сипаттаманы анықтадық.
- Ол толық болуы керек. Бұл капитанға ұқсайды, бірақ ескеру маңызды. Ол іске асырылған шешімнің барлық элементтерін егжей-тегжейлі сипаттауы керек.
- Ол өзекті болуы керек. Яғни, шешімнің ағымдағы іске асырылуына сәйкес келеді.
- Бұл түсінікті болуы керек. Оны пайдаланатын адам шешімнің қалай жүзеге асырылатынын түсінуі үшін.
Қорытындылай келе - толық, өзекті және түсінікті құжаттама.
сұхбат
Құжаттаманың сапасын бағалау үшін біз онымен тікелей жұмыс істейтіндерден сұхбат алуды жөн көрдік: NIB талдаушылары. Респонденттерге «10-ден 1-ке дейінгі шкала бойынша (толығымен келіспеймін - толықтай келісемін)» схемасы бойынша 5 мәлімдемені бағалау ұсынылды.
Өтініштер сапалы құжаттаманың сипаттамаларын және NIB құжаттарына қатысты сауалнама құрастырушылардың пікірін көрсетті.
- NIB қосымшаларының құжаттамасы жаңартылған және олардың орындалуына толығымен сәйкес келеді.
- NIB қосымшаларының орындалуы толығымен құжатталған.
- NIB қолданбаларына арналған құжаттама тек функционалды қолдау үшін қажет.
- NIB қосымшаларына арналған құжаттама оларды функционалдық қолдауға жіберу кезінде ағымдағы болып табылады.
- NIB қолданбасын әзірлеушілер нені іске асыру керектігін түсіну үшін құжаттаманы пайдаланады.
- NIB қосымшалары үшін олардың қалай жүзеге асырылатынын түсіну үшін жеткілікті құжаттама бар.
- Мен NIB жобалары бойынша құжаттаманы, егер олар аяқталса (менің командаммен) дереу жаңартамын.
- NIB қолданбасын әзірлеушілер құжаттаманы қарайды.
- Мен NIB жобалары үшін құжаттаманы қалай дайындау керектігін нақты түсінемін.
- Мен NIB жобалары үшін құжаттаманы қашан жазу/жаңарту керектігін түсінемін.
«1-ден 5-ке дейін» деп жауап беру қажетті мәліметтерді ашпауы мүмкін, сондықтан адам әрбір элементке түсініктеме қалдыра алады.
Біз мұның бәрін корпоративтік Slack арқылы жасадық – біз жай ғана жүйе талдаушыларына сауалнама жүргізуге шақыру жібердік. 15 талдаушы (Мәскеуден 9, Санкт-Петербургтен 6) болды. Сауалнама аяқталғаннан кейін біз 10 мәлімдеменің әрқайсысы үшін орташа балл шығардық, содан кейін біз оны стандарттадық.
Бұл болды.
Сауалнама көрсеткендей, сарапшылар NIB өтінімдерін жүзеге асыру толығымен құжатталған деп санауға бейім болса да, олар біржақты келісім бермейді (0.2). Нақты мысал ретінде олар бірқатар дерекқорлар мен қолданыстағы шешімдердің кезектері құжаттамамен қамтылмағанын атап өтті. Әзірлеуші талдаушыға бәрі құжатталмағанын айта алады. Бірақ әзірлеушілер құжаттаманы қарастыратын тезис де біржақты қолдау таппады (0.33). Яғни, іске асырылған шешімдердің толық емес сипатталу қаупі сақталады.
Сәйкестік оңайырақ - әлі де нақты келісім болмағанымен (0,13), сарапшылар әлі де құжаттаманы маңызды деп санауға бейім. Түсініктемелер өзектілігі бар мәселелер ортадан гөрі алдыңғы қатарда болатынын түсінуге мүмкіндік берді. Алайда олар бізге қолдау көрсету туралы ештеңе жазған жоқ.
Құжаттаманы жазу және жаңарту қажет болған кезде аналитиктердің өздері түсінеді ме дегенге келсек, келісім әлдеқайда біркелкі болды (1,33), оның ішінде оның дизайны (1.07). Бұл жерде ыңғайсыздық ретінде құжатты жүргізудің бірыңғай ережелерінің жоқтығы атап өтілді. Сондықтан «Орманға кім барады, кім отын алады» режимін қоспау үшін олар қолданыстағы құжаттаманың мысалдарына сүйене отырып жұмыс істеуі керек. Демек, құжат айналымының стандартын жасау және олардың бөліктері үшін үлгілерді әзірлеу пайдалы тілек болып табылады.
NIB қосымшалары үшін құжаттама функционалдық қолдау көрсетуге жіберу кезінде ағымдағы болып табылады (0.73). Бұл түсінікті, өйткені функционалдық қолдау көрсетуге жобаны ұсыну критерийлерінің бірі - жаңартылған құжаттама. Сондай-ақ іске асыруды түсіну жеткілікті (0.67), дегенмен кейде сұрақтар қалады.
Бірақ респонденттердің келіспегені (бірауыздан) NIB қосымшалары үшін құжаттама, негізінен, тек функционалды қолдау үшін қажет (-1.53). Құжаттаманы тұтынушылар ретінде аналитиктер жиі аталды. Команданың қалған бөлігі (әзірлеушілер) - әлдеқайда аз. Сонымен қатар, талдаушылар әзірлеушілер бірауыздан болмаса да, нені іске асыру керектігін түсіну үшін құжаттаманы пайдаланбайды деп санайды (-0.06). Айтпақшы, бұл кодты әзірлеу мен құжаттаманы жазу параллельді түрде жүретін жағдайларда да күтіледі.
Түпнұсқа дегеніміз не және бұл сандар бізге не үшін қажет?
Құжаттардың сапасын жақсарту үшін біз мыналарды шештік:
- Әзірлеушіден жазбаша құжаттарды қарауды сұраңыз.
- Мүмкін болса, алдымен құжаттаманы уақтылы жаңартыңыз.
- NIB жобаларын құжаттауға арналған стандартты жасаңыз және қабылдаңыз, осылайша әркім қандай жүйе элементтерін және қалай нақты сипатталу керектігін тез түсіне алады. Сәйкес үлгілерді әзірлеңіз.
Мұның барлығы құжаттардың сапасын жаңа деңгейге көтеруге ықпал етуі тиіс.
Кем дегенде мен солай деп үміттенемін.
Ақпарат көзі: www.habr.com