Comment nous avons évalué la qualité de la documentation

Bonjour, Habr! Je m'appelle Lesha, je suis analyste système dans l'une des équipes produits d'Alfa-Bank. Maintenant, je développe une nouvelle banque Internet pour les personnes morales et les entrepreneurs individuels.

Et lorsque vous êtes analyste, en particulier dans un tel canal, sans documentation et sans travail acharné avec lui - nulle part. Et la documentation est la 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 devrait fonctionner, mais ne fonctionne pas du tout? Pourquoi deux personnes seulement peuvent-elles comprendre la spécification, dont l'une l'a écrite?



Cependant, la documentation ne peut pas être ignorée pour des raisons évidentes. Et afin de simplifier nos vies, nous avons décidé d'évaluer la qualité de la documentation. Comment exactement nous l'avons fait et à quelles conclusions nous sommes arrivés - sous la coupe.

Qualité de la documentation

Afin de ne pas répéter le texte «New Internet Bank» plusieurs dizaines de fois, j'écrirai le NIB. Nous avons maintenant plus d'une douzaine d'équipes travaillant sur le développement de la 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'actuelle. 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.

1. Elle doit être complète. Cela semble assez 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.
2. Cela devrait être pertinent. Autrement dit, correspondent à la mise en œuvre actuelle de la solution elle-même.
3. Cela devrait être clair. Pour que la personne qui l'utilise comprenne comment la solution est mise en œuvre.

Résumé - documentation complète, pertinente et compréhensible.

Sondage

Pour évaluer la qualité de la documentation, nous avons décidé d'interviewer ceux qui travaillent directement avec elle: les analystes de la NIB. Les répondants ont été invités à évaluer 10 déclarations selon le schéma «sur une échelle de 1 à 5 (complètement en désaccord - tout à fait d'accord)».

Les allégations reflétaient les caractéristiques d'une documentation de qualité et l'opinion des compilateurs de l'enquête concernant les documents NIB.

1. La documentation sur les applications NIB est pertinente et parfaitement cohérente avec leur mise en œuvre.
2. La mise en œuvre des applications NIB est entièrement documentée.
3. La documentation sur les applications NIB n'est nécessaire que pour le support fonctionnel.
4. La documentation sur les applications NIB est pertinente au moment de leur soumission pour le support fonctionnel.
5. Les développeurs d'applications NIB utilisent la documentation pour comprendre ce dont ils ont besoin pour implémenter.
6. La documentation des applications NIB suffit pour comprendre comment elles sont implémentées.
7. Je mettrai à jour la documentation sur les projets NIB en temps opportun s'ils sont finalisés (par mon équipe).
8. Les développeurs d'applications NIB examinent la documentation.
9. J'ai une compréhension claire de la façon de documenter les projets NIB.
10. Je sais quand écrire / mettre à jour la documentation sur les projets NIB.

Il est clair que simplement la réponse «De 1 à 5» ne pouvait pas révéler les détails nécessaires, donc une personne pouvait laisser un commentaire sur chaque élément.

Nous avons fait tout cela par le biais de la société Slack - nous avons simplement envoyé une proposition aux analystes système pour répondre à l'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 établi une note moyenne pour chacune des 10 déclarations, qui a ensuite été normalisée.

Voilà ce qui s'est passé.



L'enquête a montré que, bien que les analystes soient enclins à croire que la mise en œuvre des applications NIB est entièrement documentée, ils ne donnent pas un consentement sans équivoque (0,2). À titre d'exemple concret, ils ont indiqué qu'un certain nombre de bases de données et de files d'attente des 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 effectuent un examen de la documentation n'a pas non plus reçu un soutien sans ambiguïté (0,33). Autrement dit, le risque de descriptions incomplètes des solutions mises en œuvre demeure.

C'est plus facile avec la pertinence - bien qu'il n'y ait pas d'accord non équivoque à nouveau (0,13), les analystes sont toujours enclins à considérer la documentation pertinente. Les commentaires nous ont permis de comprendre qu'il y a plus souvent des problèmes de pertinence à l'avant qu'au milieu. Certes, ils n’ont rien écrit sur le soutien.

Quant à savoir si les analystes eux-mêmes comprennent quand rédiger et mettre à jour la documentation, l'accord était déjà beaucoup plus uniforme (1,33), y compris sa conception (1,07). Ce qui a été noté 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 inclure le régime «Qui est dans la forêt, qui est pour le bois de chauffage», ils doivent travailler sur la base d'exemples de documentation existante. D'où un souhait utile - créer une norme pour la maintenance des documents, développer des modèles pour leurs parties.

La documentation sur les applications NIB est pertinente au moment de la livraison pour le support fonctionnel (0.73). C'est compréhensible, car l'un des critères de remise d'un projet au support fonctionnel est une documentation à jour. Il suffit également de comprendre la mise en œuvre (0,67), bien que parfois des questions demeurent.

Mais ce que les répondants n'étaient pas d'accord (plutôt à l'unanimité), c'est que la documentation sur les applications NIB, en principe, n'est nécessaire que pour le support fonctionnel (-1,53). Les analystes en tant que consommateurs de documentation ont été mentionnés le plus souvent. Les autres membres de l'équipe (développeurs) - beaucoup moins souvent. De plus, les analystes estiment que les développeurs n'utilisent pas de documentation pour comprendre ce dont ils ont besoin pour implémenter, mais pas à l'unanimité (-0.06). Soit dit en passant, cela est également prévu dans des conditions où le développement de code et la documentation d'écriture vont en parallèle.

Quel est le résultat et pourquoi avons-nous besoin de ces chiffres

Pour améliorer la qualité des documents, nous avons décidé de procéder comme suit:

1. Demandez au développeur d'examiner les documents écrits.
2. Si possible, mettez à jour en temps opportun la documentation, le front - en premier lieu.
3. 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 le décrire. 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.