Regardez deux versions du même diagramme d'architecture. L'une est nette : des lignes parfaitement droites, des boîtes alignées sur une grille, des angles uniformes. L'autre semble dessinée à la main, avec des traits un peu lâches, comme si quelqu'un l'avait esquissée sur un tableau blanc il y a cinq minutes. Posez-vous maintenant une question honnête. Sur laquelle vous sentiriez-vous à l'aise de griffonner ?
Presque tout le monde désigne le croquis. Ce réflexe n'est pas un hasard, et il en dit long sur la façon dont la documentation technique est réellement utilisée, ignorée ou discrètement abandonnée.
La psychologie de la finition
Un diagramme rigide et parfait au pixel près porte un message caché : il est terminé. Chaque ligne est délibérée, chaque boîte est à sa place, quelqu'un a manifestement fait un vrai effort pour lui donner un air officiel. Or ce qui est terminé n'invite pas à la modification. Cela invite à acquiescer. Quand un diagramme semble sortir d'une imprimerie, le remettre en question donne l'impression de dégrader un monument, alors la personne qui repère la file d'attente manquante ou la mauvaise flèche ne dit tout simplement rien.
Un rendu dessiné à la main fait l'inverse. Il se lit comme un travail en cours, une esquisse partagée plutôt qu'une déclaration. Cette barre abaissée est tout l'intérêt. Les gens pointent du doigt un dessin approximatif, entourent la partie qui semble fausse et disent « attends, le cache n'est pas plutôt ici maintenant ? ». L'imperfection est une invitation.
Un diagramme qui a l'air inachevé se fait corriger. Un diagramme qui a l'air terminé se fait ignorer.
L'attention va à l'idée, pas aux pixels
Il y a un second avantage, plus discret. Quand un diagramme est censé avoir l'air soigné, la personne qui le réalise commence à se focaliser sur les mauvaises choses : cette boîte est-elle alignée avec celle-là, les espacements sont-ils réguliers, pourquoi cette flèche est-elle décalée d'un pixel. Ce perfectionnisme est une taxe sur la réflexion. Il détourne l'attention de la vraie question : les boîtes et les flèches décrivent-elles correctement le système ?
Un style dessiné à la main supprime cette taxe. Personne n'attend d'un croquis qu'il soit parfaitement aligné, donc personne ne passe vingt minutes à décaler des rectangles. L'énergie reste sur les idées et sur les relations entre elles. Et comme le dessin est rapide et sans enjeu, le diagramme initial est réellement réalisé, au lieu d'être la chose que l'on compte toujours faire « quand on aura le temps de le rendre joli ».
- Les dessins approximatifs sont rapides, ils voient donc le jour au début d'une conception, quand ils sont le plus utiles.
- Peu d'enjeu signifie qu'on en jette un et qu'on le redessine plutôt que de défendre un investissement perdu.
- Comme ils ne coûtent pas cher à produire, ils ne coûtent pas cher à tenir à jour, et c'est la seule façon pour un diagramme de rester juste.
Voilà la vraie raison pour laquelle un outil de diagrammes au style dessiné à la main a tendance à produire plus de documentation, pas moins. C'est la barrière au démarrage qui tue la plupart des diagrammes, et la finition est une barrière déguisée en vertu.
Laissez le dessin s'expliquer lui-même
Une image répond admirablement à la question « qu'est-ce qui est relié à quoi » et pas du tout à « pourquoi ». C'est généralement là que les diagrammes et leurs explications écrites divergent : le dessin vit à un endroit, le paragraphe qui l'explique à un autre, et ils vieillissent à des rythmes différents.
LetDraw comble cet écart avec Expliquer le diagramme. Pointez-le vers un dessin et il transforme les formes et les connexions en une prose claire ou en Markdown : une description écrite du système qui correspond à l'image, puisqu'elle a été générée à partir d'elle. Un diagramme peut être livré avec sa propre explication, si bien que le document et le dessin restent deux vues d'une même chose au lieu de deux choses qui se contredisent.
Un style croquis, approximatif volontairement
Rien de tout cela ne plaide contre le soin. C'est un argument sur le moment où la finition aide et celui où elle nuit. Au début, quand une conception est encore malléable et que vous voulez que les gens la remettent en question, un croquis suscite les objections qui améliorent la conception. Plus tard, quand une décision est arrêtée et que vous la transmettez à un auditeur ou à une nouvelle recrue, la netteté est exactement ce qu'il faut, et elle n'est qu'à un clic.
La meilleure documentation technique est celle que les gens lisent, questionnent et tiennent à jour. Le plus souvent, c'est celle qui a l'air un peu dessinée à la main, parce qu'elle semble encore demander votre aide. Ouvrez un canevas, esquissez d'abord la version brouillonne, et laissez le diagramme mériter sa finition plus tard.