Bonjour Habr! Je m'appelle Lesha, je suis analyste système pour l'une des équipes produits d'Alfa-Bank. Je développe actuellement une nouvelle banque en ligne pour les personnes morales et les entrepreneurs individuels.
Et lorsque vous êtes analyste, surtout dans un tel canal, vous ne pouvez aller nulle part sans documentation et travailler en étroite collaboration avec elle. Et la documentation est quelque chose qui soulève toujours beaucoup de questions. Pourquoi l'application web n'est-elle pas décrite ? Pourquoi la spécification indique-t-elle comment le service doit fonctionner, mais cela ne fonctionne pas du tout comme ça ? Pourquoi seules deux personnes, dont l’une l’a écrit, peuvent-elles comprendre la spécification ?
Toutefois, la documentation ne peut être ignorée pour des raisons évidentes. Et pour nous faciliter la vie, nous avons décidé d'évaluer la qualité de la documentation. La façon exacte dont nous avons fait cela et les conclusions auxquelles nous sommes parvenus sont en deçà de la limite.
Qualité des documents
Afin de ne pas répéter plusieurs dizaines de fois « Nouvelle banque Internet » dans le texte, j'écrirai NIB. Nous avons désormais plus d'une douzaine d'équipes travaillant au développement de NIB pour les entrepreneurs et les personnes morales. De plus, chacun d'eux crée à partir de zéro sa propre documentation pour un nouveau service ou une nouvelle application Web, ou apporte des modifications à l'actuel. Avec cette approche, la documentation peut-elle, en principe, être de haute qualité ?
Et pour déterminer la qualité de la documentation, nous avons identifié trois caractéristiques principales.
- Il doit être complet. Cela ressemble plutôt à un capitaine, mais il est important de le noter. Il doit décrire en détail tous les éléments de la solution mise en œuvre.
- Cela doit être pertinent. Autrement dit, correspondre à la mise en œuvre actuelle de la solution elle-même.
- Cela devrait être compréhensible. Pour que celui qui l’utilise comprenne exactement comment la solution est mise en œuvre.
Pour résumer – une documentation complète, à jour et compréhensible.
Interview
Pour évaluer la qualité de la documentation, nous avons décidé d'interroger ceux qui travaillent directement avec elle : les analystes de NIB. Il a été demandé aux personnes interrogées d'évaluer 10 énoncés selon le schéma « Sur une échelle de 1 à 5 (pas du tout d'accord - tout à fait d'accord). »
Les déclarations reflétaient les caractéristiques de la documentation qualitative et l'opinion des compilateurs de l'enquête concernant les documents du NIB.
- La documentation des applications NIB est à jour et entièrement cohérente avec leur mise en œuvre.
- La mise en œuvre des applications NIB est entièrement documentée.
- La documentation des applications NIB n'est nécessaire que pour le support fonctionnel.
- La documentation des applications NIB est à jour au moment de leur soumission pour support fonctionnel.
- Les développeurs d'applications NIB utilisent la documentation pour comprendre ce qu'ils doivent implémenter.
- Il existe suffisamment de documentation pour les applications NIB pour comprendre comment elles sont mises en œuvre.
- Je mets rapidement à jour la documentation sur les projets NIB s'ils sont finalisés (par mon équipe).
- Les développeurs d'applications NIB examinent la documentation.
- J'ai une compréhension claire de la façon de préparer la documentation pour les projets NIB.
- Je comprends quand rédiger/mettre à jour la documentation pour les projets NIB.
Il est clair que le simple fait de répondre « De 1 à 5 » pourrait ne pas révéler les détails nécessaires, donc une personne pourrait laisser un commentaire sur chaque élément.
Nous avons fait tout cela via Slack d'entreprise - nous avons simplement envoyé une invitation aux analystes système pour qu'ils répondent à une enquête. Il y avait 15 analystes (9 de Moscou et 6 de Saint-Pétersbourg). Une fois l’enquête terminée, nous avons généré un score moyen pour chacune des 10 affirmations, que nous avons ensuite standardisé.
Il s'est avéré que c'est quoi.
L'enquête a montré que même si les analystes sont enclins à croire que la mise en œuvre des applications NIB est entièrement documentée, ils ne sont pas d'accord sans ambiguïté (0.2). À titre d'exemple spécifique, ils ont souligné qu'un certain nombre de bases de données et de files d'attente de solutions existantes n'étaient pas couvertes par la documentation. Le développeur est en mesure de dire à l'analyste que tout n'est pas documenté. Mais la thèse selon laquelle les développeurs examinent la documentation n'a pas non plus reçu de soutien sans équivoque (0.33). Autrement dit, le risque d'une description incomplète des solutions mises en œuvre demeure.
La pertinence est plus facile – même si là encore il n’y a pas d’accord clair (0,13), les analystes sont toujours enclins à considérer la documentation comme pertinente. Les commentaires nous ont permis de comprendre que les problèmes de pertinence se situent plus souvent au premier plan qu'au milieu. Cependant, ils ne nous ont rien écrit concernant le support.
Quant à savoir si les analystes eux-mêmes comprennent quand il est nécessaire de rédiger et de mettre à jour la documentation, l'accord était beaucoup plus uniforme (1,33), y compris dans sa conception (1.07). Ce qui a été noté ici comme un inconvénient, c'est l'absence de règles uniformes pour la conservation de la documentation. Par conséquent, afin de ne pas activer le mode « Qui va en forêt, qui prend du bois de chauffage », ils doivent travailler sur la base d'exemples de documentation existante. Par conséquent, il serait utile de créer une norme pour la gestion des documents et de développer des modèles pour leurs parties.
La documentation pour les applications NIB est à jour au moment de la soumission du support fonctionnel (0.73). Cela est compréhensible, car l'un des critères de soumission d'un projet au support fonctionnel est la documentation à jour. Il suffit également de comprendre la mise en œuvre (0.67), même si parfois des questions subsistent.
Mais ce avec quoi les personnes interrogées ne sont pas d'accord (à l'unanimité), c'est que la documentation pour les applications NIB n'est en principe nécessaire que pour le support fonctionnel (-1.53). Les analystes ont été mentionnés le plus souvent comme consommateurs de documentation. Le reste de l'équipe (développeurs) - beaucoup moins souvent. De plus, les analystes estiment que les développeurs n'utilisent pas la documentation pour comprendre ce qu'ils doivent implémenter, même si cela ne fait pas l'unanimité (-0.06). Ceci est d'ailleurs également attendu dans des conditions où le développement du code et la rédaction de la documentation se déroulent en parallèle.
Quel est le résultat final et pourquoi avons-nous besoin de ces chiffres ?
Pour améliorer la qualité des documents, nous avons décidé de procéder comme suit :
- Demandez au développeur d'examiner les documents écrits.
- Si possible, mettez à jour la documentation en temps opportun, en premier lieu.
- Créez et adoptez une norme pour documenter les projets NIB afin que chacun puisse comprendre rapidement quels éléments du système et comment exactement doivent être décrits. Eh bien, développez des modèles appropriés.
Tout cela devrait contribuer à élever la qualité des documents à un nouveau niveau.
Du moins je l'espère.
Source: habr.com