Ciao, Habr! Mi chjamu Lesha, sò un analista di sistemi per una di e squadre di produttu Alfa-Bank. Avà sò sviluppatu un novu bancu in linea per entità giuridiche è imprenditori individuali.
È quandu site un analista, soprattuttu in un tali canali, ùn pudete micca ghjunghje in ogni locu senza documentazione è u travagliu vicinu cun ellu. È a documentazione hè qualcosa chì sempre suscita assai dumande. Perchè l'applicazione web ùn hè micca descritta? Perchè a specificazione indica cumu si deve travaglià u serviziu, ma ùn funziona micca cusì? Perchè hè chì solu duie persone, una di quale l'hà scrittu, ponu capisce a specificazione?
Tuttavia, a documentazione ùn pò esse ignorata per ragioni evidenti. È per fà a nostra vita più faciule, avemu decisu di valutà a qualità di a documentazione. Cumu esattamente avemu fattu questu è quale cunclusioni avemu ghjuntu hè sottu à u cut.
Qualità di a documentazione
Per ùn ripetiri "New Internet Bank" parechje decine di volte in u testu, scriveraghju NIB. Avà avemu più di una decina di squadre chì travaglianu nantu à u sviluppu di NIB per l'imprenditori è e persone giuridiche. Inoltre, ognunu crea a so propria documentazione per un novu serviziu o applicazione web da zero, o cambia l'attuale. Cù questu approcciu, a documentazione pò esse in principiu di alta qualità?
È per determinà a qualità di a documentazione, avemu identificatu trè caratteristiche principali.
- Deve esse cumpletu. Questu sona piuttostu cum'è capitanu, ma hè impurtante di nutà. Deve descriverà in dettagliu tutti l'elementi di a suluzione implementata.
- Deve esse attuale. Questu hè, currisponde à l'implementazione attuale di a suluzione stessu.
- Si deve esse capisci. Cusì chì a persona chì l'utiliza capisce esattamente cumu a suluzione hè implementata.
Per sintetizà - documentazione cumpleta, aghjurnata è comprensibile.
Poll
Per valutà a qualità di a ducumentazione, avemu decisu di entrevista à quelli chì travaglianu direttamente cun ella: analisti NIB. I rispondenti sò stati dumandati à valutà 10 dichjarazioni secondu u schema "In una scala da 1 à 5 (completamente d'accordu - cumplettamente d'accordu)."
I dichjarazioni riflettevanu e caratteristiche di a documentazione qualitativa è l'opinione di i compilatori di l'inchiesta in quantu à i ducumenti NIB.
- A documentazione per l'applicazioni NIB hè aghjurnata è cumpletamente coherente cù a so implementazione.
- L'implementazione di l'applicazioni NIB hè cumplettamente documentata.
- A documentazione per l'applicazioni NIB hè necessaria solu per u supportu funziunale.
- A documentazione per l'applicazioni NIB hè attuale à u mumentu di a so presentazione per u supportu funziunale.
- I sviluppatori di applicazioni NIB utilizanu a documentazione per capisce ciò chì anu bisognu di implementà.
- Ci hè abbastanza documentazione per l'applicazioni NIB per capisce cumu sò implementate.
- Aghju aghjurnatu prestu a documentazione nantu à i prughjetti NIB si sò finalizzati (da u mo squadra).
- I sviluppatori di applicazioni NIB esaminanu a documentazione.
- Aghju una comprensione chjara di cumu preparà a documentazione per i prughjetti NIB.
- Capiscu quandu scrive / aghjurnà a documentazione per i prughjetti NIB.
Hè chjaru chì solu risponde "Da 1 à 5" puderia micca revelà i dettagli necessarii, cusì una persona puderia lascià un cumentu nantu à ogni articulu.
Avemu fattu tuttu questu attraversu Slack corporativu - avemu solu mandatu un invitu à l'analista di u sistema per piglià un sondaghju. Ci era 15 analisti (9 da Mosca è 6 da San Petruburgu). Dopu chì l'indagine hè stata cumpletata, avemu generatu un puntuatu mediu per ognuna di e dichjarazioni 10, chì avemu poi standardizatu.
Questu hè ciò chì hè accadutu.
L'indagine hà dimustratu chì, ancu s'è l'analista sò inclinati à crede chì l'implementazione di l'applicazioni NIB hè cumplettamente documentata, ùn dà micca un accordu unambigu (0.2). Cum'è un esempiu specificu, anu indicatu chì una quantità di basa di dati è fila di suluzioni esistenti ùn sò micca cuparti da documentazione. U sviluppatore hè capaci di dì à l'analista chì micca tuttu hè documentatu. Ma a tesi chì i sviluppatori riviseghjanu a documentazione ùn anu ancu ricevutu un supportu inequivocabile (0.33). Questu hè, u risicu di una descrizzione incompleta di e soluzioni implementate resta.
A rilevanza hè più faciule - ancu s'ellu ùn ci hè micca novu accordu chjaru (0,13), l'analista sò sempre inclinati à cunsiderà a documentazione pertinente. I cumenti ci anu permessu di capiscenu chì i prublemi cù pertinenza sò più spessu in u fronte chì in u mezu. Tuttavia, ùn ci anu scrittu nunda di sustegnu.
In quantu l'analisti stessi capiscenu quandu hè necessariu di scrive è aghjurnà a documentazione, l'accordu era assai più uniforme (1,33), cumpresu u so disignu (1.07). Ciò chì era nutatu quì cum'è un inconveniente era a mancanza di regule uniformi per mantene a documentazione. Per quessa, per ùn accende micca u modu "Quale va à a furesta, chì piglia a legna", anu da travaglià basatu annantu à esempi di documentazione esistenti. Dunque, un desideriu utile hè di creà un standard per a gestione di documenti è di sviluppà mudelli per e so parti.
A documentazione per l'applicazioni NIB hè attuale à u mumentu di a presentazione per u supportu funziunale (0.73). Questu hè comprensibile, perchè unu di i criteri per invià un prughjettu per u supportu funziunale hè a documentazione aghjurnata. Hè ancu abbastanza per capiscenu l'implementazione (0.67), ancu s'ellu ci hè qualchì volta e dumande.
Ma ciò chì i rispondenti ùn anu micca d'accordu cù (abbastanza unanimu) era chì a documentazione per l'applicazioni NIB, in principiu, hè solu necessariu per u supportu funziunale (-1.53). L'analisti sò stati citati più spessu cum'è cunsumatori di documentazione. U restu di a squadra (sviluppatori) - assai menu spessu. Inoltre, l'analista crede chì i sviluppatori ùn utilizanu micca a documentazione per capisce ciò chì deve esse implementatu, ancu s'ellu ùn hè micca unanimu (-0.06). Questu, per via, hè ancu previstu in e cundizioni induve u sviluppu di codice è a scrittura di documentazione procedenu in parallelu.
Chì ci hè u fondu è perchè avemu bisognu di sti numeri?
Per migliurà a qualità di i documenti, avemu decisu di fà i seguenti:
- Dumandate à u sviluppatore per rivisione i documenti scritti.
- Sè pussibule, aghjurnà a documentazione in una manera puntuale, prima prima.
- Crea è aduttà un standard per documentà i prughjetti NIB in modu chì tutti ponu capisce rapidamente quale elementi di u sistema è cumu esattamente deve esse descritti. Ebbè, sviluppate mudelli adattati.
Tuttu chistu deve aiutà à elevà a qualità di i documenti à un novu livellu.
Almenu spergu cusì.
Source: www.habr.com