Voici une liste de bonnes pratiques à adopter pour améliorer la qualité d’une documentation technique.

 

Adoptez un style rédactionnel cohérent

Ecrivez de la même manière dans l’ensemble de votre documentation. Si vous choisissez un verbe pour une action particulière, utiliser le même verbe partout. Un lecteur n’aime pas trouver un nouveau terme pour quelque chose qu’on lui a déjà expliqué en utilisant un synonyme.

Adoptez également des règles strictes pour les listes à puces et les titres par exemple. Si vous ne mettez pas de points dans vos listes à puces, n’en mettez jamais. Si vous mettez une majuscule seulement au premier terme d’un titre, faites-en de même dans tous vos titres.

 

Formatez vos documents uniformément

Tout comme le contenu du texte, soyez cohérent avec son formatage dans vos documents. Si vous ne soulignez pas vos titres, ne décidez pas d’en souligner un en particulier. Si vous utilisez du bleu dans un tableau, utilisez cette couleur pour tous vos tableaux. Si vous utilisez une police particulière pour un type de contenu, réutilisez là à chaque fois que vous rencontrez ces contenus.

 

Ciblez votre public

Tout comme un journal politique ne s’adresse pas à ses lecteurs de la même façon qu’un magazine de jeux vidéo, la rédaction technique comporte, de par la diversité des secteurs auxquels elle s’attache, de nombreux types de public.

Il est donc primordial, lorsque l’on rédige une documentation, d’identifier d’une part le public auquel on s’adresse, et d’autre part, l’environnement dans lequel la documentation est consultée.

Pour cibler son public, on peut par exemple se poser les questions suivantes :

  • Quel est le niveau d’expertise métier du lecteur ?
  • Quel est le type de produit que je documente ? Grand public, produit de niche, open-source ?
  • Comment la doc est-elle consultée ? Sur un ordinateur, un support mobile sur le terrain ?

Les réponses à ces questions permettent d’identifier son public et d’adapter la structure et le style rédactionnel.

 

Limitez la longueur des procédures

Essayez de limiter la longueur de vos procédures à 7±2  étapes maximum. Au-delà de ce nombre, le lecteur aura perdu le fil conducteur de la tâche. Si votre procédure dépasse les 9 étapes, vous pouvez la diviser.

D’ailleurs, la règle du 7±2  s’applique également aux phrases (7±2  mots) et aux paragraphes (7±2  phrases).

 

Indiquez le résultat de vos procédures

Lorsque vous écrivez une procédure, il est important que l’utilisateur sache que les actions qu’il a effectuées durant cette procédure ont abouti au résultat attendu. Décrire en une phrase simple, à la fin de la procédure, ce qu’il se passe à l’écran permet de « valider » que la procédure s’est correctement déroulé. C’est un feedback pour l’utilisateur.

Exemple                                            

  • Cliquer sur New.
  • Entrer le nom du nouvel utilisateur.
  • Cliquer sur Créer.

L’utilisateur apparaît dans le panneau de gauche.

 

Explicitez vos titres

Les titres sont l’un des points de référence essentiel pour l’utilisateur. Ce sont ces titres qui vont orienter et guider le lecteur sur ce qu’il va lire ou ne pas lire. Les titres se doivent donc d’être explicites, clairs, concis, et de décrire immédiatement le type d’information que l’on va trouver dans la section correspondante. Par exemple, le titre « A propos des utilisateurs » doit seulement comporter des explications sur les utilisateurs. Il ne contient pas de verbe d’action induisant des tâches à effectuer. A l’inverse, le titre « Créer un utilisateur » correspond à une tâche métier, et comportera une procédure. Avoir des titres explicites vous permettra aussi d’insérer des liens vers des sujets connexes rapidement, sans avoir à modifier le libellé du lien en question.

 

Ecrivez au présent, à la voix active

La meilleure manière d’écrire une documentation claire et concise est d’utiliser autant que possible la voix active. La voix passive allonge les phrases. Le passé et le futur ne permettent pas de situer précisément les actions qu’un utilisateur doit effectuer à un moment t. Evitez également les modaux comme « « vous devriez » ou « le logiciel pourrait ». Ils provoquent un doute sur la pertinence d’une action ou d’un comportement au sein du logiciel.

Adressez-vous directement à votre lecteur.

 

Concentrez-vous sur les objectifs métier

Un utilisateur qui lit une documentation n’est pas en train de faire son travail. Il consulte la documentation car il a un objectif métier à atteindre en utilisant une fonction du logiciel qu’il ne comprend ou ne maîtrise pas. La documentation doit lui permettre de résoudre le problème le plus rapidement possible. L’utilisateur ne veut pas lire d’explications interminables, il veut trouver la réponse à sa question et continuer son travail.

Orienter sa documentation sur des tâches et des workflows métier permet non seulement d’aider efficacement l’utilisateur dans sa quête d’information, mais également d’intégrer cette documentation aux processus métier. Elle devient un complément à l’utilisation d’une application.

 

Utilisez les symboles avec précaution

L’une des tendances actuelle dans le domaine de la communication technique est d’utiliser des symboles, jolis et stylisés pour transmettre l’information en lieu et place du texte. Très bien. Cela habille un document et permet de rendre l’espace de lecture plus aéré et reposant.

Il faut cependant rester vigilant sur la perception de ces symboles par des publics de cultures différentes. Certains symboles, très évidents en Europe, ne seront peut-être pas compris de la même façon en Asie. De la même façon, des utilisateurs de générations différentes pourront comprendre un symbole différemment.

Enfin, et c’est une problématique encore trop peu prise en compte, les personnes visuellement déficientes peuvent interpréter de façon erronée les couleurs qui habillent les symboles.