Ciao, Habr! Mi chiamo Lesha, sono un analista di sistema per uno dei team di prodotto di Alfa-Bank. Ora sto sviluppando una nuova banca online per persone giuridiche e imprenditori individuali.
E quando sei un analista, soprattutto in un canale del genere, non puoi andare da nessuna parte senza documentazione e lavorare con essa. E la documentazione è qualcosa che solleva sempre molte domande. Perché l'applicazione web non è descritta? Perché le specifiche indicano come dovrebbe funzionare il servizio, ma non funziona affatto così? Perché solo due persone, una delle quali l'ha scritto, possono comprendere le specifiche?
Tuttavia, la documentazione non può essere ignorata per ovvi motivi. E per semplificarci la vita, abbiamo deciso di valutare la qualità della documentazione. Come esattamente lo abbiamo fatto e a quali conclusioni siamo arrivati è sotto il taglio.
Qualità della documentazione
Per non ripetere decine di volte nel testo “Nuova Banca Internet”, scriverò NIB. Ora abbiamo più di una dozzina di team che lavorano allo sviluppo di NIB per imprenditori e persone giuridiche. Inoltre, ognuno di loro crea da zero la propria documentazione per un nuovo servizio o applicazione web, oppure apporta modifiche a quella attuale. Con questo approccio, la documentazione può essere in linea di principio di alta qualità?
E per determinare la qualità della documentazione, abbiamo identificato tre caratteristiche principali.
- Deve essere completo. Sembra un po' da capitano, ma è importante notarlo. Dovrebbe descrivere in dettaglio tutti gli elementi della soluzione implementata.
- Deve essere attuale. Cioè, corrispondono all'attuale implementazione della soluzione stessa.
- Dovrebbe essere comprensibile. In modo che chi lo utilizza capisca esattamente come viene implementata la soluzione.
In sintesi: documentazione completa, aggiornata e comprensibile.
Опрос
Per valutare la qualità della documentazione, abbiamo deciso di intervistare chi ci lavora direttamente: gli analisti NIB. Agli intervistati è stato chiesto di valutare 10 affermazioni secondo lo schema “Su una scala da 1 a 5 (completamente in disaccordo – completamente d’accordo)”.
Le dichiarazioni riflettevano le caratteristiche della documentazione qualitativa e l'opinione dei compilatori dell'indagine riguardo ai documenti NIB.
- La documentazione per le applicazioni NIB è aggiornata e pienamente coerente con la loro implementazione.
- L'implementazione delle applicazioni NIB è completamente documentata.
- La documentazione per le applicazioni NIB è necessaria solo per il supporto funzionale.
- La documentazione per le applicazioni NIB è aggiornata al momento della loro presentazione per il supporto funzionale.
- Gli sviluppatori di applicazioni NIB utilizzano la documentazione per comprendere cosa devono implementare.
- La documentazione disponibile per le applicazioni NIB è sufficiente per comprendere come vengono implementate.
- Aggiorno tempestivamente la documentazione sui progetti NIB se vengono finalizzati (dal mio team).
- Gli sviluppatori di applicazioni NIB esaminano la documentazione.
- Ho una chiara comprensione di come preparare la documentazione per i progetti NIB.
- Capisco quando scrivere/aggiornare la documentazione per i progetti NIB.
È chiaro che rispondere semplicemente “Da 1 a 5” potrebbe non rivelare i dettagli necessari, quindi una persona potrebbe lasciare un commento su ciascuna voce.
Abbiamo fatto tutto questo tramite Slack aziendale: abbiamo semplicemente inviato un invito agli analisti di sistema per partecipare a un sondaggio. Gli analisti erano 15 (9 di Mosca e 6 di San Pietroburgo). Una volta completato il sondaggio, abbiamo generato un punteggio medio per ciascuna delle 10 affermazioni, che abbiamo poi standardizzato.
Si è scoperto che è quello che.
Dall'indagine è emerso che, sebbene gli analisti siano propensi a credere che l'implementazione delle applicazioni NIB sia completamente documentata, non danno un accordo inequivocabile (0.2). Ad esempio, hanno sottolineato che un certo numero di database e code di soluzioni esistenti non erano coperti da documentazione. Lo sviluppatore è in grado di dire all'analista che non tutto è documentato. Ma anche la tesi secondo cui gli sviluppatori esaminano la documentazione non ha ricevuto un supporto inequivocabile (0.33). Resta cioè il rischio di una descrizione incompleta delle soluzioni implementate.
La pertinenza è più semplice: anche se non esiste ancora un accordo chiaro (0,13), gli analisti sono ancora propensi a considerare rilevante la documentazione. I commenti ci hanno permesso di capire che i problemi rilevanti sono più spesso in primo piano che nel mezzo. Tuttavia non ci hanno scritto nulla riguardo al sostegno.
Per quanto riguarda la comprensione da parte degli analisti quando è necessario scrivere e aggiornare la documentazione, l'accordo era molto più uniforme (1,33), compresa la sua concezione (1.07). Ciò che è stato notato come inconveniente è stata la mancanza di regole uniformi per la conservazione della documentazione. Pertanto, per non attivare la modalità “Chi va nel bosco, chi prende la legna da ardere”, devono lavorare sulla base di esempi di documentazione esistente. Pertanto, un desiderio utile è quello di creare uno standard per la gestione dei documenti e sviluppare modelli per le loro parti.
La documentazione per le applicazioni NIB è aggiornata al momento della presentazione per il supporto funzionale (0.73). Ciò è comprensibile, perché uno dei criteri per presentare un progetto per il supporto funzionale è la documentazione aggiornata. È sufficiente anche comprendere l'implementazione (0.67), anche se a volte rimangono delle domande.
Ma ciò su cui gli intervistati non sono d'accordo (all'unanimità) è che la documentazione per le domande NIB, in linea di principio, è necessaria solo per il supporto funzionale (-1.53). Gli analisti venivano citati più spesso come consumatori di documentazione. Il resto del team (sviluppatori) - molto meno spesso. Inoltre, gli analisti ritengono che gli sviluppatori non utilizzino la documentazione per capire cosa devono implementare, anche se non all'unanimità (-0.06). Ciò, tra l'altro, è previsto anche in condizioni in cui lo sviluppo del codice e la scrittura della documentazione procedono in parallelo.
Qual è il risultato finale e perché abbiamo bisogno di questi numeri?
Per migliorare la qualità dei documenti, abbiamo deciso di fare quanto segue:
- Chiedi allo sviluppatore di rivedere i documenti scritti.
- Se possibile, aggiorna la documentazione in modo tempestivo, prima di tutto.
- Creare e adottare uno standard per documentare i progetti NIB in modo che tutti possano capire rapidamente quali elementi del sistema e come esattamente dovrebbero essere descritti. Bene, sviluppa modelli appropriati.
Tutto ciò dovrebbe contribuire a elevare la qualità dei documenti a un nuovo livello.
Almeno lo spero.
Fonte: habr.com