Hola Habr! Mi nombre es Lesha, soy analista de sistemas en uno de los equipos de productos de Alfa-Bank. Ahora estoy desarrollando un nuevo banco de Internet para entidades legales y empresarios individuales.
Y cuando eres analista, especialmente en un canal así, sin documentación y trabajo duro con él, en ninguna parte. Y la documentación es lo que siempre plantea muchas preguntas. ¿Por qué no se describe la aplicación web? ¿Por qué la especificación indica cómo debería funcionar el servicio, pero no funciona en absoluto? ¿Por qué solo dos personas pueden entender la especificación, una de las cuales la escribió?
Sin embargo, la documentación no puede ser ignorada por razones obvias. Y para simplificar nuestras vidas, decidimos evaluar la calidad de la documentación. Cómo exactamente hicimos esto y a qué conclusiones llegamos, debajo del corte.
Calidad de documentación
Para no repetir el texto "New Internet Bank" varias docenas de veces, escribiré el NIB. Ahora tenemos más de una docena de equipos trabajando en el desarrollo de la NIB para emprendedores y personas jurídicas. Además, cada uno de ellos, desde cero, crea su propia documentación para un nuevo servicio o aplicación web, o realiza cambios en el actual. Con este enfoque, ¿puede la documentación, en principio, ser de alta calidad?
Y para determinar la calidad de la documentación, identificamos tres características principales.
- Debe estar completo. Suena bastante capitana, pero es importante tener en cuenta. Debe describir en detalle todos los elementos de la solución implementada.
- Debería ser relevante. Es decir, corresponde a la implementación actual de la solución en sí.
- Debe quedar claro. Para que la persona que lo utiliza comprenda cómo se implementa la solución.
Resumiendo: documentación completa, relevante y comprensible.
Encuesta
Para evaluar la calidad de la documentación, decidimos entrevistar a quienes trabajan directamente con ella: analistas de NIB. Se pidió a los encuestados que calificaran 10 declaraciones de acuerdo con el esquema "En una escala de 1 a 5 (completamente en desacuerdo, totalmente de acuerdo)".
Las acusaciones reflejaban las características de la documentación de calidad y la opinión de los compiladores de la encuesta con respecto a los documentos NIB.
- La documentación sobre las aplicaciones NIB es relevante y totalmente coherente con su implementación.
- La implementación de las aplicaciones NIB está completamente documentada.
- La documentación sobre las aplicaciones NIB solo es necesaria para el soporte funcional.
- La documentación sobre las solicitudes de NIB es relevante en el momento de su presentación para soporte funcional.
- Los desarrolladores de aplicaciones NIB usan documentación para comprender lo que necesitan implementar.
- La documentación para las aplicaciones NIB es suficiente para comprender cómo se implementan.
- Actualizaré la documentación de los proyectos de NIB de manera oportuna si están finalizados (por mi equipo).
- Los desarrolladores de aplicaciones NIB revisan la documentación.
- Tengo una comprensión clara de cómo documentar proyectos de NIB.
- Entiendo cuándo escribir / actualizar documentación sobre proyectos NIB.
Está claro que simplemente la respuesta "De 1 a 5" no pudo revelar los detalles necesarios, por lo que una persona podría dejar un comentario sobre cada elemento.
Hicimos todo esto a través del Slack corporativo: simplemente enviamos una propuesta a los analistas del sistema para que realizaran la encuesta. Hubo 15 analistas (9 de Moscú y 6 de San Petersburgo). Después de completar la encuesta, formamos una calificación promedio para cada una de las 10 declaraciones, que luego se normalizó.
Esto es lo que pasó.
La encuesta mostró que, aunque los analistas se inclinan a creer que la implementación de aplicaciones NIB está completamente documentada, no dan un consentimiento inequívoco (0.2). Como ejemplo concreto, indicaron que una serie de bases de datos y colas de soluciones existentes no estaban cubiertas por la documentación. El desarrollador puede decirle al analista que no todo está documentado. Pero la tesis de que los desarrolladores realizan una revisión de la documentación tampoco recibió un soporte inequívoco (0.33). Es decir, el riesgo de descripciones incompletas de las soluciones implementadas permanece.
Es más fácil con la relevancia: aunque no hay un acuerdo inequívoco nuevamente (0.13), los analistas aún están inclinados a considerar la documentación relevante. Los comentarios nos permitieron entender que con mayor frecuencia hay problemas con relevancia en el frente que en el medio. Es cierto que no escribieron nada sobre el respaldo.
En cuanto a si los analistas mismos entienden cuándo escribir y actualizar la documentación, el acuerdo ya era mucho más uniforme (1.33), incluido su diseño (1.07). Lo que se observó como un inconveniente aquí es la falta de reglas uniformes para mantener la documentación. Por lo tanto, para no incluir el régimen de “Quién está en el bosque, quién es para leña”, deben trabajar sobre la base de ejemplos de documentación existente. De ahí un deseo útil: crear un estándar para el mantenimiento de documentos, desarrollar plantillas para sus partes.
La documentación sobre las aplicaciones NIB es relevante en el momento de la entrega del soporte funcional (0.73). Es comprensible, porque uno de los criterios para entregar un proyecto al soporte funcional es la documentación actualizada. También es suficiente entender la implementación (0.67), aunque a veces quedan preguntas.
Pero lo que los encuestados no estaban de acuerdo (por unanimidad) es que la documentación sobre las aplicaciones NIB, en principio, solo es necesaria para el soporte funcional (-1.53). Los analistas como consumidores de documentación fueron mencionados con mayor frecuencia. Los miembros restantes del equipo (desarrolladores), con mucha menos frecuencia. Además, los analistas creen que los desarrolladores no usan la documentación para comprender lo que necesitan implementar, aunque no de manera unánime (-0.06). Esto, por cierto, también se espera en condiciones en las que el desarrollo de código y la escritura de documentación van en paralelo.
¿Cuál es el resultado y por qué necesitamos estos números?
Para mejorar la calidad de los documentos, decidimos hacer esto:
- Pídale al desarrollador que revise los documentos escritos.
- Si es posible, actualice oportunamente la documentación, el frente, en primer lugar.
- Cree y adopte un estándar para documentar proyectos de NIB para que todos puedan comprender rápidamente qué elementos del sistema y cómo describirlo. Bueno, desarrolle plantillas apropiadas.
Todo esto debería ayudar a elevar la calidad de los documentos a un nuevo nivel.
Al menos eso espero.