Hola, Habr! Em dic Lesha, sóc analista de sistemes d'un dels equips de productes d'Alfa-Bank. Ara estic desenvolupant un nou banc en línia per a persones jurídiques i emprenedors individuals.
I quan ets analista, sobretot en un canal així, no pots arribar enlloc sense documentació i treballar amb ella. I la documentació és una cosa que sempre planteja moltes preguntes. Per què no es descriu l'aplicació web? Per què l'especificació indica com hauria de funcionar el servei, però no funciona així? Per què només dues persones, una de les quals l'ha escrit, poden entendre l'especificació?
Tanmateix, la documentació no es pot ignorar per raons òbvies. I per facilitar-nos la vida, vam decidir avaluar la qualitat de la documentació. Com ho vam fer exactament i a quines conclusions vam arribar està per sota del tall.
Qualitat de la documentació
Per no repetir "New Internet Bank" diverses dotzenes de vegades al text, escriuré NIB. Ara tenim més d'una desena d'equips treballant en el desenvolupament de NIB per a emprenedors i persones jurídiques. A més, cadascun d'ells crea la seva pròpia documentació per a un nou servei o aplicació web des de zero, o bé fa canvis a l'actual. Amb aquest enfocament, la documentació pot ser en principi d'alta qualitat?
I per determinar la qualitat de la documentació, hem identificat tres característiques principals.
- Ha d'estar complet. Això sembla més aviat capità, però és important tenir-ho en compte. Hauria de descriure amb detall tots els elements de la solució implementada.
- Ha de ser rellevant. És a dir, corresponen a la implementació actual de la pròpia solució.
- Hauria de ser comprensible. Perquè la persona que l'utilitzi entengui exactament com s'implementa la solució.
En resum: documentació completa, actualitzada i comprensible.
Опрос
Per avaluar la qualitat de la documentació, hem decidit entrevistar als qui hi treballen directament: els analistes del NIB. Es va demanar als enquestats que avaluessin 10 afirmacions segons l'esquema "En una escala de l'1 al 5 (totalment en desacord - completament d'acord)".
Les declaracions reflectien les característiques de la documentació qualitativa i l'opinió dels compiladors de l'enquesta sobre els documents del NIB.
- La documentació de les aplicacions NIB està actualitzada i totalment coherent amb la seva implementació.
- La implementació de les aplicacions NIB està totalment documentada.
- La documentació per a les aplicacions NIB només és necessària per al suport funcional.
- La documentació de les sol·licituds de NIB està vigent en el moment de la seva presentació per al suport funcional.
- Els desenvolupadors d'aplicacions NIB utilitzen la documentació per entendre què han d'implementar.
- Hi ha prou documentació perquè les aplicacions NIB entenguin com s'implementen.
- Actualitzo ràpidament la documentació dels projectes NIB si estan finalitzats (pel meu equip).
- Els desenvolupadors d'aplicacions NIB revisen la documentació.
- Tinc una comprensió clara de com preparar la documentació per als projectes NIB.
- Entenc quan redactar/actualitzar la documentació dels projectes NIB.
És evident que simplement respondre "De l'1 al 5" pot no revelar els detalls necessaris, de manera que una persona podria deixar un comentari sobre cada element.
Tot això ho vam fer a través de Slack corporatiu: simplement vam enviar una invitació als analistes del sistema perquè fessin una enquesta. Hi havia 15 analistes (9 de Moscou i 6 de Sant Petersburg). Després de completar l'enquesta, vam generar una puntuació mitjana per a cadascuna de les 10 afirmacions, que després vam estandarditzar.
Això és el que va passar.
L'enquesta va mostrar que, tot i que els analistes s'inclinen a creure que la implementació de les aplicacions NIB està totalment documentada, no donen un acord inequívoc (0.2). Com a exemple concret, van assenyalar que una sèrie de bases de dades i cues de solucions existents no estaven cobertes per la documentació. El desenvolupador és capaç de dir a l'analista que no tot està documentat. Però la tesi que els desenvolupadors revisen la documentació tampoc va rebre un suport inequívoc (0.33). És a dir, es manté el risc de descripció incompleta de les solucions implementades.
La rellevància és més fàcil: encara que de nou no hi ha un acord clar (0,13), els analistes encara s'inclinen a considerar la documentació rellevant. Els comentaris ens van permetre entendre que els problemes de rellevància es troben més sovint al davant que al mig. Tanmateix, no ens van escriure res sobre el suport.
Pel que fa a si els mateixos analistes entenen quan cal redactar i actualitzar documentació, l'acord era molt més uniforme (1,33), inclòs el seu disseny (1.07). El que es va assenyalar aquí com a inconvenient va ser la manca de normes uniformes per al manteniment de la documentació. Per tant, per no activar la modalitat “Qui va al bosc, qui agafa llenya”, han de treballar a partir d'exemples de documentació existent. Per tant, un desig útil és crear un estàndard per a la gestió de documents i desenvolupar plantilles per a les seves parts.
La documentació de les sol·licituds de NIB està vigent en el moment de la presentació del suport funcional (0.73). Això és comprensible, perquè un dels criteris per presentar un projecte de suport funcional és la documentació actualitzada. També és suficient per entendre la implementació (0.67), encara que de vegades queden preguntes.
Però amb el que els enquestats no estaven d'acord (per unanimitat) és que la documentació per a les sol·licituds de NIB, en principi, només és necessària per al suport funcional (-1.53). Els analistes van ser esmentats més sovint com a consumidors de documentació. La resta de l'equip (desenvolupadors) - molt menys sovint. A més, els analistes creuen que els desenvolupadors no utilitzen la documentació per entendre què han d'implementar, encara que no per unanimitat (-0.06). Això, per cert, també s'espera en condicions en què el desenvolupament de codi i l'escriptura de la documentació es desenvolupen paral·lelament.
Quin és el resultat final i per què necessitem aquests números?
Per millorar la qualitat dels documents, hem decidit fer el següent:
- Demaneu al desenvolupador que revisi els documents escrits.
- Si és possible, actualitzeu la documentació de manera oportuna, primer al davant.
- Creeu i adopteu un estàndard per documentar projectes NIB perquè tothom pugui entendre ràpidament quins elements del sistema i com s'han de descriure exactament. Bé, desenvolupeu plantilles adequades.
Tot això hauria d'ajudar a elevar la qualitat dels documents a un nou nivell.
Almenys espero que sí.
Font: www.habr.com