Pourquoi faire de la doc c’est *¤&@§ !!!10 min read

« Oh non, faut encore faire de la doc ! »

On entend souvent des soupirs de ce genre lorsqu’on annonce à un membre de l’équipe qu’il va devoir écrire de la doc technique pour le projet. Nous sommes ingénieurs et nous avons dû en écrire beaucoup. Alors oui, la doc c’est rébarbatif mais c’est un investissement nécessaire et rentable ! Elle permet de poser le projet, mettre à plat nos pensées, les communiquer aux autres et sauvegarder le tout pour facilement les retrouver (Aaah la magie du Ctrl+F). Cette activité serait beaucoup moins pénible sans certains pièges d’improductivité qui génèrent de l’inertie, démotivent, voire même stressent les équipes. Sauf que ces piège, on peut les éviter…


Point sur le vocabulaire

Avant d’aller plus loin, voici les définitions de quelques termes utilisés dans cet article.

WYSIWYG
WYSIWYG sont les initiales de What You See Is What You Get. Cela désigne un type d’outil logiciel dans lequel ce qu’on voit à l’écran dans le mode d’édition (d’un document par exemple) est fidèle à ce qu’on aura une fois imprimé.

Template
Terme anglais couramment utilisé pour désigner tous types de modèles de documents pré-remplis. Le but étant de capitaliser sur leur contenu récurant pour en améliorer l’exhaustivité. Voir les fichiers d’extensions “.dot”, “.dotx” ou “.dotm” pour Word ; “.xlt”, “.xltx” ou “.xltm” pour Excel ; “.oft” pour Outlook, …


Voici une liste non exhaustive de tout ce qui est déplaisant quand on “fait de la doc” avec quelques pistes pour les contourner.

Écrire sur un sujet qu’on ne maîtrise pas

François Damiens dans “OSS 117 : Le caire nid d’espion” – Gaumont 2006

Il arrive souvent qu’une seule personne soit désignée pour écrire l’intégralité d’un document. Cela évite de devoir gérer les plannings de plusieurs personnes. On se dit qu’ainsi le contenu sera homogène. Cependant il est possible que le rédacteur ne maîtrise pas toutes les compétences requises sur le projet pour en écrire une description complète. C’est une situation qu’a rencontré une personne que nous avons interrogée.

On m’avait chargé de rédiger des tests à dérouler sur un produit pour s’assurer qu’il réponde à tous les besoins du client. Ce fût une expérience compliquée car je ne connaissais strictement rien à l’une des technos du produit. J’ai donc dû demandé à l’expert sur cette partie spécifique, comprendre son fonctionnement et écrire un test cohérent et pertinent. Il a fallu plusieurs itérations du doc et un peu de temps mais ça a fini par fonctionner. Bon je suis monté en compétence sur ce sujet mais on a perdu un peu de temps et j’ai eu pas mal de sueurs froides.”

Ancien collaborateur ingénieur

Attribuer une tâche à une personne qui ne la maîtrise pas est source de stress. Mais on y est parfois contraint par manque de disponibilité des experts.

Aujourd’hui, de plus en plus d’outils collaboratifs facilitent la contribution de chacun au projet (les partages de documents et les commentaires sur Microsoft Word ou Google Docs par exemple). Nous avons rencontré de nombreuses sociétés qui mettent en place des tutoriels vidéos pour vulgariser rapidement une spécificité technique afin que le plus grand nombre ait les bases. Enfin, faire du “re-use”, c’est-à-dire réutiliser ou s’inspirer d’anciens documents pour écrire les nouveaux, quand cela est possible, permet d’en construire rapidement une première version. Il sera alors plus aisé de l’adapter au cas présent, plutôt de l’écrire de zéro (“from scratch“).

Les traitements de texte WYSIWYG

WYSIWYG est un acronyme anglais : “What You See Is What You Get”. Il signifie “ce que vous voyez est ce que vous obtiendrez ». C’est le principe des éditeurs de textes les plus répandus, comme Microsoft Word. Le document, tel que vous le rédigez à l’écran, aura le même aspect une fois imprimé. Ces logiciels sont très pratiques car très intuitifs et faciles à prendre en main. Tout le monde sait se servir de Word !

Seulement lorsqu’on rédige de la doc en entreprise, on va peut-être devoir ajouter des commentaires, enclencher le suivi des modifications, gérer des tableaux, mettre des champs automatiques (numéros de pages, etc)… L’inconvénient c’est que cela amène le logiciel à consommer beaucoup de mémoire vive de l’ordinateur, pour réussir à afficher la page “telle que vous l’imprimerez”. Cela est parfaitement indolore pour un document de quelques dizaines de pages. Mais lorsque celui-ci avoisine la centaine de pages, les limitations du WYSIWYG se font ressentir. La réactivité de l’éditeur s’amoindrit et il n’est pas rare qu’il « plante » (c’est du vécu).

Outre le Ctrl+S toutes les 5 minutes, il existe des alternatives à ce type d’éditeurs de texte. LaTex en est un exemple libre et gratuit. Cependant il nécessite de se former un minimum. Son principe est de séparer le contenu d’un document de sa mise en page. D’un côté, vous rédigez votre texte à l’aide de balises. Ces balises permettent d’identifier les titres, les images, les graphiques, les tableaux… De l’autre vous paramétrez le rendu de ces éléments (la tailles, l’emplacement des images, la police d’écriture…). Puis vous « exécutez » LaTex pour qu’il génère votre document final à partir de ces fichiers. Et ce n’est qu’après cette génération que vous pouvez enfin voir à quoi ressemble votre document. Il vous faudra peut-être réitérer l’opération plusieurs fois en modifiant les paramètres pour obtenir le document tel que vous l’imaginiez.

Heureusement pour les éditeurs de texte courants, les outils de récupération de fichiers et les sauvegardes automatiques sont de plus en plus performants et répandus.

Les circuits de relecture

Généralement, un document fait partie du corpus de livrables pour client. Pour s’assurer que le document rédigé répond aux critères de qualité de l’entreprise, celui-ci peut être relu par un ou plusieurs « validateurs » suivant sa complexité.

Les attentes de chacun de ces validateurs peuvent être différentes. Ils n’ont peut-être pas tous la même connaissance du projet. Une banale relecture peut alors se transformer en un débat sur le projet lui-même. Ici encore il y a nécessité de structurer ces relectures :

  1. Sélectionner des validateurs pour tout le projet sans en changer. Éventuellement leur attribuer la relecture de certaines sections du document et pas son intégralité.
  2. Planifier les périodes limitées pour la relecture.
  3. Collecter leurs remarques, dans un tableur par exemple. Celui-ci permettra de toutes les avoir dans un seul endroit et de leur attribuer un statut de prise en compte.

Le degré de détail

Ensemble de Mandelbrot, fractale. Plus vous zoomez, plus vous voyez de détails. Crédit AnthonyStC

Un document décrivant un produit, quel qu’il soit, peut tenir en deux pages comme sur plusieurs centaines. La différence réside dans la granularité du détail de la description.

Et il n’y a pas de solution miracle. Soit on fait le strict nécessaire pour démarrer le développement du projet ; c’est peu coûteux mais on risque de tomber rapidement sur un problème qu’on n’avait pas anticipé. Soit on prend le temps de rédiger un document très précis ; au-delà du coût considérable d’un tel document, ses relectures par des validateurs peuvent générer beaucoup de reprises.

Un bon compromis est de rédiger une première version. Celle-ci doit permettre à quelqu’un d’extérieur à l’équipe de comprendre les tenants et aboutissants du projet. Et puis il faut la mettre à jour très régulièrement tout au long du projet. Cependant il faut rester vigilant pour ne pas tomber dans la sur-qualité. Ils ne faut pas mettre des efforts disproportionnés dans la documentation au détriment d’activités prioritaires.

Le manque d’intérêt pour le document produit

Certains documents n’ont d’autre but que d’être archivés. Ils viendront remplir une base de données inerte qui ne sera jamais consultée. Cette documentation n’existe alors que pour respecter un processus traditionnel, historique de gestion du projet.

Il est peut-être nécessaire de reconsidérer la pertinence de ce processus car ces documents ont un coût. Quelle considération aura le rédacteur pour son travail, sachant pertinemment le peu d’intérêt qu’on lui témoignera ?

En revanche, cette documentation peut être valorisée ! Elle peut servir de base de départ pour concevoir les nouveaux projets similaires. S’ils sont stockés dans une base de données informatique (du type Sharepoint), un simple moteur de recherche permettra rapidement d’identifier les documents les plus pertinents pour être réutilisés. En itérant sur cette mine d’informations, l’entreprise capitalise sur ces connaissances et transforme ses archives figées en un atout stratégique et vivant. Le rédacteur prend alors conscience qu’il construit un savoir sur lequel se reposeront ses successeurs !

Le manque de cadre

Le syndrome de la page blanche n’est pas l’apanage des écrivains. Se retrouver en charge de la rédaction d’un document complexe et volumineux peut se révéler être une épreuve difficile si on ne sait pas par quel angle l’attaquer. Je commence par cet aspect ? ou par celui-ci ? Suis-je certain de ne rien oublier ? Est-ce que c’est suffisamment détaillé ? Moi je connais le projet mais pour quelqu’un d’extérieur ? Est-ce que je dois expliquer le vocabulaire ? …

Un bon point de départ est de s’inspirer d’éléments connus et vérifiés. On reprend la structure d’un document similaire sur un précédent projet et on parcourt ses sections. Certaines nous donnerons des idées pour rendre le nouveau document plus exhaustif, d’autres pourront être reprises telles quelles, puis détaillées, améliorées.

Le plus efficace étant de se construire des modèles de documents pré-remplis avec toutes les sections possibles qu’on complétera ou effacera suivant leur pertinence pour le projet donné. Ainsi au fur et à mesure des itérations, toute l’activité de documentation s’améliore et devient de plus en plus qualitative.

Le site FYI propose un très grand nombre de modèles de documents (templates) de tout type pour Getting Work Done (abattre du travail, c’est leur slogan) !

Conclusion

Ce qui se dégage de ces constats, c’est que ce n’est pas tellement la documentation en elle-même qui est pénible. Mais c’est le manque de méthodologie et de structuration du processus de rédaction qui le rend fastidieux.

Et vous ?

Ces facteurs d’inertie vous sont-ils familiers ?
En rencontrez-vous d’autres ?
Comment faîtes-vous pour y remédier ?
Utilisez-vous des outils de collaboration pour faciliter le travail en équipe ? Lesquels ?
Avez-vous mis en place des méthodes de Lean Management ? de Knowledge Management ?
Quel est votre retour d’expérience ?

Related Posts

Leave a Reply