Ola, Habr! Chámome Lesha, son analista de sistemas para un dos equipos de produtos de Alfa-Bank. Agora estou a desenvolver un novo banco en liña para persoas xurídicas e emprendedores individuais.
E cando es analista, especialmente nunha canle deste tipo, non pode chegar a ningún lado sen documentación e traballar de preto con ela. E a documentación é algo que sempre suscita moitas dúbidas. Por que non se describe a aplicación web? Por que a especificación indica como debería funcionar o servizo, pero non funciona así? Por que só dúas persoas, unha das cales a escribiu, poden entender a especificación?
Non obstante, a documentación non se pode ignorar por razóns obvias. E para facilitarnos a vida, decidimos avaliar a calidade da documentación. Como fixemos isto exactamente e a que conclusións chegamos está por debaixo do corte.
Calidade da documentación
Para non repetir "New Internet Bank" varias ducias de veces no texto, escribirei NIB. Agora temos máis dunha ducia de equipos traballando no desenvolvemento de NIB para emprendedores e persoas xurídicas. Ademais, cada un deles crea dende cero a súa propia documentación para un novo servizo ou aplicación web, ou ben realiza cambios no actual. Con este enfoque, pode a documentación en principio ser de alta calidade?
E para determinar a calidade da documentación, identificamos tres características principais.
- Debe estar completo. Isto parece un capitán, pero é importante ter en conta. Debe describir en detalle todos os elementos da solución implementada.
- Debe ser actual. É dicir, corresponder á implantación actual da propia solución.
- Debería ser comprensible. Para que a persoa que o utilice entenda exactamente como se implementa a solución.
En resumo: documentación completa, actualizada e comprensible.
Опрос
Para avaliar a calidade da documentación, decidimos entrevistar aos que traballan directamente con ela: os analistas do NIB. Pedíuselles aos entrevistados que avaliaran 10 afirmacións segundo o esquema "Nunha escala do 1 ao 5 (totalmente en desacordo - totalmente de acordo)."
As declaracións reflectían as características da documentación cualitativa e a opinión dos compiladores das enquisas sobre os documentos do NIB.
- A documentación das aplicacións NIB está actualizada e totalmente coherente coa súa implementación.
- A implementación das aplicacións NIB está totalmente documentada.
- A documentación das aplicacións NIB só é necesaria para o soporte funcional.
- A documentación das solicitudes de NIB está actualizada no momento da súa presentación para o soporte funcional.
- Os desenvolvedores de aplicacións NIB usan documentación para comprender o que precisan implementar.
- Hai documentación suficiente para que as aplicacións NIB comprendan como se implementan.
- Actualizo de inmediato a documentación dos proxectos do NIB se están finalizados (polo meu equipo).
- Os desenvolvedores de aplicacións NIB revisan a documentación.
- Teño unha comprensión clara de como preparar a documentación para proxectos NIB.
- Entendo cando escribir/actualizar a documentación dos proxectos NIB.
Está claro que simplemente responder "Do 1 ao 5" pode non revelar os detalles necesarios, polo que unha persoa pode deixar un comentario sobre cada elemento.
Fixemos todo isto a través de Slack corporativo: simplemente enviamos unha invitación aos analistas de sistemas para que realizaran unha enquisa. Había 15 analistas (9 de Moscova e 6 de San Petersburgo). Despois de completar a enquisa, xeramos unha puntuación media para cada unha das 10 afirmacións, que logo estandarizamos.
Isto foi o que pasou.
A enquisa mostrou que aínda que os analistas están inclinados a crer que a implementación das aplicacións NIB está totalmente documentada, non dan un acordo inequívoco (0.2). Como exemplo concreto, sinalaron que unha serie de bases de datos e colas de solucións existentes non estaban cubertas pola documentación. O programador é capaz de dicirlle ao analista que non todo está documentado. Pero a tese de que os desenvolvedores revisan a documentación tampouco recibiu un apoio inequívoco (0.33). É dicir, permanece o risco de descrición incompleta das solucións implementadas.
A relevancia é máis fácil: aínda que de novo non hai un acordo claro (0,13), os analistas seguen inclinados a considerar a documentación relevante. Os comentarios permitíronnos entender que os problemas de relevancia están máis frecuentemente á fronte que no medio. Non obstante, non nos escribiron nada sobre o respaldo.
En canto a se os propios analistas entenden cando é necesario redactar e actualizar documentación, o acordo foi moito máis uniforme (1,33), incluído o seu deseño (1.07). O que aquí se sinalou como un inconveniente foi a falta de normas uniformes para o mantemento da documentación. Polo tanto, para non activar o modo “Quen vai ao bosque, quen leva leña”, teñen que traballar a partir de exemplos da documentación existente. Polo tanto, un desexo útil é crear un estándar para a xestión de documentos e desenvolver modelos para as súas partes.
A documentación para as solicitudes de NIB está actualizada no momento da presentación do soporte funcional (0.73). Isto é comprensible, porque un dos criterios para presentar un proxecto de apoio funcional é a documentación actualizada. Tamén é suficiente para comprender a implementación (0.67), aínda que ás veces quedan dúbidas.
Pero co que os entrevistados non estaban de acordo (por unanimidade) foi que a documentación para as solicitudes de NIB, en principio, só é necesaria para o soporte funcional (-1.53). Os analistas mencionáronse con máis frecuencia como consumidores de documentación. O resto do equipo (desenvolvedores) - con moita menos frecuencia. Ademais, os analistas consideran que os desenvolvedores non utilizan a documentación para comprender o que precisan implementar, aínda que non por unanimidade (-0.06). Isto, por certo, tamén se espera en condicións nas que o desenvolvemento de código e a escritura de documentación procedan paralelamente.
Cal é o resultado final e por que necesitamos estes números?
Para mellorar a calidade dos documentos, decidimos facer o seguinte:
- Pídalle ao programador que revise os documentos escritos.
- Se é posible, actualice a documentación de forma oportuna, primeiro.
- Crea e adopta un estándar para documentar proxectos NIB para que todos poidan comprender rapidamente que elementos do sistema e como se deben describir exactamente. Ben, desenvolve modelos axeitados.
Todo isto debería axudar a elevar a calidade dos documentos a un novo nivel.
Polo menos o espero.
Fonte: www.habr.com