Aujourd’hui, alors que je lisais de la documentation au travail, je me suis enfin rendu compte du détail qui me pousse tantôt à dire qu’un document est intéressant, et tantôt qu’il est totalement inutile.
Ce détail, cette chose insignifiante, c’est simplement ça : « il suffit de. »
N’est-ce pas fantastique ?
Ce n’est rien en soit, c’est un tout petit bout de texte que l’on colle au début d’une réponse qui est censée apporter des éclaircissements, mais en fait, elle indique au lecteur de manière totalement masquée que la personne qui répond, celle-là même qui est chargée d’écrire la documentation qui doit te sauver la vie, cette personne en fait, n’a absolument rien compris à l’utilité de la documentation qu’elle est en train d’écrire, et pourrait aussi bien parler de fleures que de cuisine mexicaine que la réponse ne te serais toujours d’aucune utilité.
Je m’explique :
La question sur laquelle je suis tombé dans notre FAQ était la suivante : « Comment filtrer une relation en fonction de sa classe cible ? »
La réponse : « Il suffit de créer un champ bla bla bla… avec bla bla bla… dont chaque bla bla bla… correspond à un bla bla bla… et de définir le bla bla bla… sur la relation. »
J’ai bla bla blaté les parties importantes de la réponse, parce que mine de rien, ce genre d’informations, on les fait payer par nos gentils clients. Cela dit, et après près de 3 ans sur le produit, et sans les bla bla bla (vous n’y perdez rien, je vous rassure), il m’a fallu bien 10 minutes pour en comprendre le sens, sans même être sûr que c’était la bonne façon de l’interpréter, alors le client qui voit ça, lui, il y passera facilement une bonne heure, et viendra certainement nous en reparler très rapidement par mail, simplement parce que ce n’était pas clair (et pour sûr, ça ne l’est pas).
Le pire, dans cette réponse, c’est que le rédacteur te prend directement de haut en sous-entendant que si te ne sais pas faire ça, c’est que franchement, t’es un gentil benêt, et vu que « chez lui, ça marche, » évidemment, tu n’as aucun moyen de pointer du doigt le problème.
En consultant des mails de réponses que j’ai pu faire au fil du temps, je me rends compte maintenant que la plupart des problèmes que j’ai pu rencontrer en expliquant un correctif ou une fonctionnalité (aller-retour intempestifs de mails avec le client, avec n+1 voir n+2 en copie), venaient d’un « il suffit de » au tout début.
Alors, bon, c’est clair, je n’aime pas être prit par la main et que l’on m’explique à chaque fois qu’en appuyant sur le truc, c’est un clic, et qu’à l’écran, le pointeur, on peut le bouger avec la souris-qui-fait-clic ; personne n’aime être prit pour un enfant, mais je pense que personne n’a encore plus envie d’être prit pour un crétin incapable de résoudre son problème tout seul en suivant la documentation magnifiquement écrite par Dieu lui-même.
L’écriture de documentation est quelque chose qui ne devrait pas passer à la trappe aussi facilement. C’est un métier à part entière ; certains développeurs ne sont tout simplement pas fait pour ça, mais en tous cas, il ne faudrait jamais considérer que c’est moins intéressant que le code qui est exécuté derrière.