¡Hola Habr! Mi nombre es Lesha, soy analista de sistemas de uno de los equipos de productos de Alfa-Bank. Ahora estoy desarrollando un nuevo banco en línea para personas jurídicas y empresarios individuales.
Y cuando eres analista, especialmente en un canal de este tipo, no puedes llegar a ninguna parte sin documentación y trabajar estrechamente con ella. Y la documentación es algo 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 así en absoluto? ¿Por qué sólo dos personas, una de las cuales la escribió, pueden entender la especificación?
Sin embargo, la documentación no puede ignorarse por razones obvias. Y para hacernos la vida más fácil, decidimos evaluar la calidad de la documentación. Cómo exactamente hicimos esto y a qué conclusiones llegamos se encuentra debajo del corte.
Calidad de la documentación
Para no repetir "Nuevo Banco de Internet" varias docenas de veces en el texto, escribiré NIB. Ahora contamos con más de una docena de equipos trabajando en el desarrollo de NIB para emprendedores y personas jurídicas. Además, cada uno de ellos crea su propia documentación para un nuevo servicio o aplicación web desde cero 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, hemos identificado tres características principales.
- Debe estar completo. Esto suena más bien a capitán, pero es importante tenerlo en cuenta. Debe describir en detalle todos los elementos de la solución implementada.
- Debe ser relevante. Es decir, corresponder a la implementación actual de la propia solución.
- Debería ser comprensible. Para que la persona que lo utilice entienda exactamente cómo se implementa la solución.
En resumen: documentación completa, actualizada y comprensible.
Entrevista
Para valorar la calidad de la documentación decidimos entrevistar a quienes trabajan directamente con ella: los analistas del NIB. Se pidió a los encuestados que evaluaran 10 afirmaciones según el esquema "En una escala de 1 a 5 (totalmente en desacuerdo - completamente de acuerdo)".
Las declaraciones reflejaron las características de la documentación cualitativa y la opinión de los compiladores de la encuesta sobre los documentos NIB.
- La documentación de las aplicaciones NIB está actualizada y es totalmente coherente con su implementación.
- La implementación de aplicaciones NIB está completamente documentada.
- La documentación para las aplicaciones NIB solo se necesita para soporte funcional.
- La documentación para las solicitudes NIB está actualizada en el momento de su envío para soporte funcional.
- Los desarrolladores de aplicaciones NIB utilizan la documentación para comprender lo que necesitan implementar.
- Existe suficiente documentación para que las aplicaciones NIB comprendan cómo se implementan.
- Actualizo rápidamente la documentación de los proyectos NIB si están finalizados (por mi equipo).
- Los desarrolladores de aplicaciones NIB revisan la documentación.
- Tengo una comprensión clara de cómo preparar documentación para proyectos NIB.
- Entiendo cuándo escribir/actualizar documentación para proyectos NIB.
Está claro que simplemente responder “Del 1 al 5” podría no revelar los detalles necesarios, por lo que una persona podría dejar un comentario sobre cada ítem.
Hicimos todo esto a través de Slack corporativo: simplemente enviamos una invitación a los analistas de sistemas para que realizaran una encuesta. Asistieron 15 analistas (9 de Moscú y 6 de San Petersburgo). Una vez completada la encuesta, generamos una puntuación promedio para cada una de las 10 afirmaciones, que luego estandarizamos.
Resultó que eso es lo que.
La encuesta mostró que, aunque los analistas se inclinan a creer que la implementación de las aplicaciones NIB está completamente documentada, no están de acuerdo de manera inequívoca (0.2). Como ejemplo específico, señalaron que varias 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 revisan la documentación tampoco recibió un apoyo inequívoco (0.33). Es decir, persiste el riesgo de una descripción incompleta de las soluciones implementadas.
La relevancia es más fácil: aunque tampoco hay un acuerdo claro (0,13), los analistas todavía se inclinan a considerar que la documentación es relevante. Los comentarios nos permitieron comprender que los problemas de relevancia suelen estar más al frente que en el medio. Sin embargo, no nos escribieron nada sobre el respaldo.
En cuanto a si los propios analistas entienden cuándo es necesario redactar y actualizar la documentación, el acuerdo fue mucho más uniforme (1,33), incluido su diseño (1.07). Lo que aquí se señaló como inconveniente fue la falta de reglas uniformes para el mantenimiento de la documentación. Por tanto, para no activar el modo “Quién va al bosque, quién recoge leña”, hay que trabajar basándose en ejemplos de documentación existente. Por tanto, un deseo útil es crear un estándar para la gestión de documentos y desarrollar plantillas para sus partes.
La documentación para las aplicaciones NIB está actualizada en el momento de la presentación para soporte funcional (0.73). Esto es comprensible, porque uno de los criterios para presentar un proyecto para soporte funcional es la documentación actualizada. También es suficiente comprender la implementación (0.67), aunque a veces quedan dudas.
Pero con lo que los encuestados no estuvieron de acuerdo (bastante unánimemente) fue con que la documentación para las aplicaciones NIB, en principio, sólo es necesaria para el soporte funcional (-1.53). Los analistas fueron mencionados con mayor frecuencia como consumidores de documentación. El resto del equipo (desarrolladores), con mucha menos frecuencia. Además, los analistas creen que los desarrolladores no utilizan la documentación para comprender lo que necesitan implementar, aunque no de forma unánime (-0.06). Esto, por cierto, también se espera en condiciones en las que el desarrollo del código y la redacción de la documentación se realizan en paralelo.
¿Cuál es el resultado final y por qué necesitamos estos números?
Para mejorar la calidad de los documentos, decidimos hacer lo siguiente:
- Pídale al desarrollador que revise los documentos escritos.
- Si es posible, actualice la documentación de manera oportuna, primero el frente.
- Cree y adopte un estándar para documentar proyectos NIB para que todos puedan comprender rápidamente qué elementos del sistema y cómo se deben describir exactamente. Bueno, desarrolle plantillas apropiadas.
Todo esto debería contribuir a elevar la calidad de los documentos a un nuevo nivel.
Por lo menos eso espero.
Fuente: habr.com