Dessiner pour écrire

Le rédacteur technique ne peut expliquer que ce qu’il a compris. Cela peut paraître évident. Mais nous sommes tous confrontés à des délais de plus en plus serrés. Les ingénieurs n’ont en outre pas le temps de nous détailler les fonctionnalités de leurs produits. Pressés de publier, nous risquons alors de fournir des informations peu utiles pour l’utilisateur. Passer du temps en début de projet sur la création de schémas permet cependant de livrer en temps et en heure une documentation de qualité.

Le rédacteur technique n’a souvent pas de formation initiale d’ingénieur. Tant mieux pour les utilisateurs. En adoptant une attitude de Candide, il est leur meilleur ambassadeur auprès des équipes de R&D. Modeste et critique à la fois, il doit constamment valider sa compréhension du produit auprès des ingénieurs. Il instaurera ainsi un climat de confiance avec les équipes techniques et fournira aux clients une aide précieuse.

Les schémas sont particulièrement adaptés aux descriptions de flux

Mais les mots peuvent être trompeurs. Le rédacteur technique pourra toujours « pondre » un texte sur un sujet qu’il maîtrise mal. Mais cette pratique, assimilable à du mauvais journalisme, produira plus de bruit que de sens. Les ingénieurs sollicités pour la validation reliront le texte en diagonale dans les transports en commun. Complétant ou rectifiant inconsciemment les informations manquantes ou erronées, ils valideront une documentation de piètre qualité. Les manuels techniques ainsi créés rejoindront la cohorte de ceux qu’on ne lit pas. Et tout le monde y perdra : le client, le rédacteur technique et l’entreprise.

Il existe heureusement un moyen simple d’obtenir une véritable validation de la part des ingénieurs : dessiner des schémas. Un schéma est en effet non ambigu et correspond plus à la manière de raisonner des ingénieurs que le texte. Une erreur qui aurait pu passer inaperçue dans les détours d’une phrase sautera immédiatement aux yeux de votre interlocuteur. Tel le Boileau du mode d’emploi, vous remettrez cent fois (ou un peu moins) votre croquis sous Illustrator. Et ne vous inquiétez pas de déranger les développeurs : acquis dorénavant au « Release early, release often » du développement en mode bazar, ils ne rechigneront jamais à vous aider à comprendre l’objet qu’il créent avec passion !

Ce n’est pas le moment d’avoir la fierté mal placée : les erreurs de compréhension sont des étapes normales et même nécessaires de tout apprentissage ! Et tout d’abord, le but du rédacteur technique n’est pas de briller aux yeux des ingénieurs, mais de rendre service aux clients. Parce qu’il fera les mêmes erreurs que les futurs utilisateurs du produit, le rédacteur technique pourra leur éviter de nombreuses frustrations et pertes de temps, améliorant singulièrement leur satisfaction et l’image de l’entreprise.

Exemple vécu. J’étais le seul rédacteur en charge de la documentation d’un logiciel de filtrage de flux Internet. Le fonctionnement du produit était assez complexe, et aucun diagramme de flux complet n’existait. Chaque développeur de l’équipe de R&D travaillait séparément sur son module. En interviewant le directeur technique et les développeurs, je me suis aperçu qu’il m’était impossible d’expliquer comment configurer et utiliser le produit si je n’avais pas une vision parfaitement claire dont les flux passaient d’un module à l’autre.

Je me suis donc mis à faire circuler des flux dans un diagramme comme des trains dans une gare de triage. Plusieurs réunions ont permis de faire valider le schéma par tous les intervenants : directeur technique, directeur marketing, développeurs et responsable qualité. Au bout d’un moment, cependant, je me suis inquiété d’avoir passé de longues journées à ne rien écrire. Mais la rédaction a ensuite coulé de source. Le premier jet n’a fait l’objet que de modifications mineures avant la publication, en temps et en heure.

Sur la base de ce schéma, j’ai pu donc créer un plan de la documentation, par tâche à réaliser par l’utilisateur, et non par module technique. L’utilisateur veut en effet savoir comment réaliser une action, quel que soit le nombre de fonctionnalités ou de modules auxquels elle fait appel, pas connaître de manière exhaustive le fonctionnement de chaque module.

Par exemple, si je veux couper du saucisson avec un couteau suisse, je n’ai pas besoin de savoir que ce dernier permet également de tourner des vis. Cette information est parasitaire. Inversement, si je veux regarder un DVD sur ma télévision, j’aimerais trouver toute l’information nécessaire dans un seul document - ce qui est rarement le cas, le lecteur et le téléviseur étant vendus séparément.

Pour chaque tâche, j’ai placé en introduction un schéma simplifié qui ne présentait que les flux concernés. Le guide précisait bien que ces schémas n’étaient pas parfaitement exacts sur le plan technique et renvoyait à chaque fois à la version complète insérée en référence. Chaque schéma disposait de légendes numérotées décrivant le traitement des flux de manière chronologique.

Il est déjà suffisamment difficile de monter un meuble Ikea accompagné d’un schéma dépourvu de texte. La difficulté à comprendre sans le support des mots un processus immatériel devient insurmontable.

Le budget alloué à la communication technique n’autorisait pas le recours à un graphiste pour réaliser une version finale des schémas. Les schémas que j’avais créés sous le logiciel de dessin vectoriel Inkscape ont donc été publiés tels quels, et même repris par le marketing dans des présentations. Dans un projet ultérieur, j’ai quand même pu apprécier la valeur ajoutée apportée par un graphiste professionnel (voir l’exemple ci-dessous).

Extrait de la documentation de NuFirewall, distribuée sous licence Creative Commons CC-BY-NC-SA.

Identification du premier paquet de connexion


Copyright 2010 EdenWall Technologies - License Creative Commons CC-BY-NC-SA

  1. L’utilisateur lance une application accédant à des ressources dont l’accès nécessite son identification.
  2. L’application ouvre une connexion vers la ressource distante et émet un premier paquet ; ce paquet est intercepté par le module de filtrage. La connexion est identifiable par le quadruplet :
    • adresse IP source,
    • port source,
    • adresse IP de destination,
    • port de destination.
  3. Le module de filtrage transmet le paquet reçu au module décisionnel.
  4. Le module décisionnel analyse le paquet reçu (en particulier l’adresse IP source) et demande aux agents NuAgent présents sur la machine correspondante la liste des identifiants des connexions en attente. À l’aide de cette liste, le module décisionnel associe l’identité de l’utilisateur à la connexion.
  5. Le module décisionnel interroge le référent de filtrage et vérifie que l’utilisateur dispose des droits pour établir cette connexion.
  6. Le module décisionnel envoie sa décision au module de filtrage.
  7. Le module de filtrage applique la décision au paquet.
  8. Si la connexion est autorisée, le paquet poursuit sa route.

Pour la petite histoire, à la sortie de la documentation, l’un des développeurs a pleuré d’émotion (n’est-ce pas Julien ). La documentation devenait un peu comme la partie émergée de l’iceberg, et le très beau travail qu’il avait réalisé au niveau du code se reflétait partiellement au niveau de la documentation.

Donc, dans le débat récurrent (voire à la limite du troll) « faut-il illustrer la documentation technique ? », il est utile de se demander de quelles illustrations l’on parle. Si la valeur des captures d’écran me semble très douteuse, ces dernières pouvant diminuer le rapport signal sur bruit d’une documentation, les schémas facilitent nettement la compréhension des processus nécessaires à l’accomplissement d’une tâche.

Si Napoléon Bonaparte a dit « Un bon croquis vaut mieux qu’un long discours », la corporation des réacteurs techniques devrait le choisir comme son saint patron. En utilisant peut-être une version modifiée de la citation : « Pour faire un bon discours, fais d’abord un bon croquis ».

Commentaires

En cliquant par curiosité sur « Translate this page » dans la page de résultats Google, j'ai eu la surprise de constater que la première phrase de cet article, « Le rédacteur technique ne peut expliquer que ce qu'il a compris », est automatiquement traduite en anglais par « The technical writer can not explain what he understood. » Apparemment, le constat de la version originale vaut également pour Google Translate !

Ajouter un commentaire

Plain text

  • Aucune balise HTML autorisée.
  • Les adresses de pages web et de courriels sont transformées en liens automatiquement.
  • Les lignes et les paragraphes vont à la ligne automatiquement.
CAPTCHA
Si vous êtes un robot, ne remplissez pas ce champ.
16 + 1 =
Solve this simple math problem and enter the result. E.g. for 1+3, enter 4.