Comment devrais-je rendre moins effrayant pour une équipe de créer des diagrammes?
Le contexte
Je suis un fervent partisan de diagrammes clairs et illustratifs dans la documentation. Lorsqu'elles sont correctement réalisées, elles améliorent beaucoup deux aspects: la compréhension de la documentation et le temps qu'un développeur passe à lire la documentation lorsqu'il a besoin de se rappeler quelque chose qu'il a déjà lu.
Le seul outil que j'ai trouvé qui (1) est en ligne (rien à installer), (2) est facile à utiliser, (3) n'impose pas de contraintes spécifiques (contrairement aux outils UML), (4) et permet d'intégrer le vecteur les informations à l'intérieur d'une image PNG pour une édition future sont draw.io . Bien qu'il soit pratique, comme tout outil de dessin en ligne, il présente un inconvénient majeur pour l'utilisation spécifique des diagrammes intégrés dans la documentation: une fois le diagramme créé, il faut des étapes supplémentaires pour le modifier, par rapport aux étapes qu'il faut pour modifier du texte dans un fichier Markdown.
Le problème est que tôt ou tard, les choses changent. Prenons, par exemple, ce schéma qui illustre une partie du protocole que j'ai développé pour communiquer avec les appareils Arduino:
Plus d'une chose peut changer:
- Je peux décider que je n'ai plus besoin de CRC. Ou que CRC devrait prendre 16 bits à la place.
- Ou la valeur magique à deux bits
0b10avant que la longueur ne devienne soudainement0b11. - Ou "zone" dans la deuxième ligne peut être renommée en "catégorie".
- Ou il peut être judicieux de placer le bloc de ligne avant le niveau et les blocs de zone.
Voici un autre exemple:
Ici, je peux vouloir:
- Changer une résistance,
- Changez les broches,
- Ajouter ou supprimer des composants,
- Changez la couleur d'une LED.
Si j'effectue l'un de ces changements, j'ai le choix:
- Soit je télécharge le PNG, allez sur draw.io, importez le PNG, modifiez-le, exportez-le, déplacez-le dans le répertoire où il appartient et validez mes modifications. Cela pourrait prendre quelques minutes.
- Ou je garde le diagramme obsolète, ce qui signifie que je ne pourrais faire confiance à aucun de mes diagrammes pour les anciens projets quelques années plus tard.
- Ou je me débarrasse du diagramme, et plus tard, je dois lire la description textuelle au lieu de simplement apercevoir l'image.
Problème
Lorsque je travaille en équipe, je remarque constamment que les diagrammes créent deux problèmes:
Certaines personnes trouvent qu'il est trop difficile de les changer et ne se soucient pas si elles deviennent obsolètes.
Certaines personnes ont peur que les diagrammes soient obsolètes et ont donc choisi une autre stratégie: éviter un changement ou une refactorisation qui rendrait le code différent du diagramme. Essentiellement, s'il est logique dans le projet correspondant au premier diagramme de renommer "zone" en "catégorie", ils conserveront le terme "zone", car le changement est tout simplement trop complexe. Ou s'il est logique de passer au CRC 16 bits, ils inventeront les raisons de conserver un CRC 8 bits.
Je comprends parfaitement ces gens et je fais parfois de même.
Question
Ma question est de savoir ce qui pourrait être fait, au niveau technique ou humain, pour prévenir ou au moins réduire ces situations, afin d'encourager les projets à avoir de grands schémas à jour, sans crainte de changer les choses qui sont incluses dans les diagrammes?
Les réponses que je cherche pourraient être quelque chose comme: "Eh bien, vous pouvez utiliser ceci ou cela pour générer comme par magie les diagrammes à la volée sur la base d'un fichier de configuration ..." ou "Vous pouvez faire ceci ou cela pour faire croire aux gens que la mise à jour des diagrammes est facile et devrait faire partie de leur travail quotidien ... "ou" Vous pouvez analyser les diagrammes et les faire correspondre au code source afin d'échouer la construction s'ils sont obsolètes ... "
Cela nécessite vraiment une approche à deux volets: des outils automatisés, comme le suggère Ewan, ainsi que l'inclusion de mises à jour de ces diagrammes dans le cadre du travail.
Les outils automatisés attraperont les fruits bas, mais il y aura des diagrammes qui ne peuvent tout simplement pas être générés par programme en raison de la complexité ou nécessitant un format hautement personnalisé. De plus, vous ne pouvez pas générer un diagramme basé sur du code ou du matériel qui n'existe pas encore.
Dans une moindre mesure, je le rencontre moi-même quotidiennement. Nos diagrammes ont tendance à être des diagrammes de classe UML et des diagrammes de séquence. Des outils existent pour générer des diagrammes de classes à partir de code, mais ils ne fonctionnent pas très bien pour du code non encore écrit. De plus, il est plus facile de comprendre les diagrammes UML qui ne contiennent qu'un sous-ensemble organisé de classes. La mise à jour de ces diagrammes prend du temps, ce qui ajoute au travail, mais l'équipe y voit unilatéralement la valeur. En tant que tel, notre équipe décompose les choses en morceaux beaucoup plus petits pour tenir compte du temps supplémentaire nécessaire pour conserver ces informations, ce qui permet de communiquer les changements de conception. Étant un projet agile, cela se traduit par moins d'unités de fonctionnalité par point d'histoire et un plus grand nombre d'histoires pour compléter une fonctionnalité.
Avant d'estimer le travail, un développeur doit faire quelques recherches pour identifier à peu près quels diagrammes doivent être mis à jour. Plus tard, cela devient une tâche dans notre plan de sprint, que nous bloquons généralement la tâche de développeur.
La mise à jour d'un diagramme pour passer d'un CRC 8 bits à un CRC 16 bits doit être traitée essentiellement de la même manière que toute autre tâche. Vous devez le planifier, identifier les choses dont il dépend et les choses qu'il bloque, ce qui vous donne l'ordre de faire les choses. Après cela, l'équipe comprendra les attentes de mise à jour de la documentation dans le cadre normal du processus d'ingénierie. Puisqu'ils identifient ce travail à l'avance, cela ne viendra pas comme un choc, ni comme quelque chose de plus. Cela devient une étape naturelle dans le processus pour donner vie à un élément.
Ne soyez pas surpris si les estimations de fonctionnalités similaires commencent à augmenter. Embrassez cela. Ne le combattez pas. En ayant des tâches clairement définies, vous pouvez justifier l'augmentation des estimations à la direction. L'augmentation des estimations donnera à votre équipe le temps d'apprendre ces compétences et de devenir compétent. Au fil du temps, vous verrez peut-être le nombre de fonctionnalités destinées aux utilisateurs revenir simplement parce que l'équipe a eu plus de pratique. J'ai connu une telle augmentation de la production juste au dernier sprint, mais pour une sorte de tâche sans rapport avec votre question.
Pendant plusieurs mois, nous nous sommes concentrés sur les tests automatisés, que l'équipe combat depuis près de 4 ans. J'ai travaillé avec l'équipe pour décomposer les histoires en morceaux si petits que je ne pouvais presque pas croire qu'il s'agissait d'histoires au lieu de tâches de développement. Une fonctionnalité qui aurait pu prendre 2-3 histoires était maintenant de 6 à 10 histoires au triple et au quadruplement du total des points d'histoire. Notre dernière version était assez lugubre, mais wow l'équipe a-t-elle beaucoup appris. Les points d'histoire par sprint n'ont pas changé pendant cette période, nous avons juste accompli moins de fonctionnalités.
Soudain, et sans avertissement, nous avons écrasé le dernier sprint et l'équipe a plus que doublé sa vitesse. Il s'avère que ces 3 mois de ralentissements ont normalisé les tests automatisés dans le cadre de notre processus, et l'équipe a vraiment atteint son rythme. Personne ne s'est battu pour écrire des tests automatisés. Cela fait partie de la routine, et c'est la clé. Donnez à l'équipe les cycles de rechange pour intégrer la nouvelle chose à sa routine. Donnez-leur le temps de prendre une habitude.
Je constate que les estimations des récits diminuent maintenant, parce que les gens ont eu plus de pratique, et je pense que cela reflète la réduction des "inconnues" dans leurs estimations. Là où il aurait pu y avoir 8 points pour faire du travail de développement et écrire un test, maintenant je vois cela se résumer à 3 et 5 points. Vous devriez voir un modèle similaire avec l'introduction de mises à jour de diagrammes dans le cadre de votre processus.
Donc, tout se résume à:
- Décomposez la fonctionnalité - vers le bas.
- Rechercher quels diagrammes devront être mis à jour avant d'estimer le travail
- Planifiez les mises à jour des documents comme toute autre tâche liée au développement
- Accepter une fonctionnalité réduite par unité d'estimation (ou une augmentation globale de l'estimation par fonctionnalité)
- Et donnez aux gens une chance de pratiquer.
Je recommanderais d'utiliser un outil qui génère le diagramme de manière progressive.
Par exemple, la syntaxe DOT pour les graphiques https://www.graphviz.org/doc/info/lang.html
ou visualisation neo4j
Je suis sûr que vous pouvez trouver quelque chose pour les schémas électriques, pour des trucs plus personnalisés, vous devrez peut-être écrire quelque chose. Mais pour les documents html, cela pourrait être du javascript intégré.
Cela signifie un peu de travail acharné au début, mais permet aux futurs éditeurs de modifier facilement certaines propriétés de base du diagramme sans avoir à dessiner quoi que ce soit