La documentation/Rédaction technique/Rédaction d'un manuel d'utilisation

Un manuel d'utilisation, ou encore mode d'emploi, notice ou règle du jeu dans le cas d'un jeu, est un ouvrage devant permettre l'utilisation d'un produit : objet manufacturé (machine, outil, équipement de protection, …) ou logiciel. Bien entendu, le manuel sera très différent selon le public visé (grand public ou spécialistes, opérateurs ou encadrement) et la complexité du produit. Cela va d'une simple affiche expliquant comment installer une imprimante, un petit livret de quelques pages indiquant les réglages d'un casque de vélo, jusqu'à plusieurs wagons de papier dans le cas d'un avion de combat.

Le manuel peut être sur papier et/ou au format électronique : fichier PDF — il peut s'agir alors simplement du document papier à imprimer, ou bien d'un document avec des liens hypertextuels — ou aide en ligne — il s'agit alors d'une sorte de site Web.

Ce wikilivre propose quelques considérations générales sur la rédaction d'un manuel d'utilisation.

Préambule utilité et objectifs

Le syndrome du bricoleur du dimanche est illustré par la boutade (légèrement misandre) suivante :

Comment faire pour qu'un homme n'ouvre pas un livre ? Il suffit d'écrire « mode d'emploi » dessus.

On peut la transposer aisément dans le domaine informatique :

Comment faire pour qu'un informaticien n'ouvre pas un fichier ? Il suffit de l'appeler lisezmoi ou readme.

C'est là un des malheurs des modes d'emploi : souvent, ils ne sont pas lus. La culture « usenet » a d'ailleurs une réponse toute faite pour ce syndrome : RTFM, « relis ton foutu manuel » (read the fucking manual).

À partir de là, certains en sont venus à considérer que le seul intérêt d'un manuel d'utilisation était de pouvoir rétorquer à l'utilisateur : « mais si, c'est écrit page n, vous n'aviez qu'à lire », et de bâcler ce qui est une obligation contractuelle. Une manière bien pratique de ne pas se remettre en question.

Pourtant, qui n'a pas pesté contre un manuel mal traduit ou issu d'une traduction automatique, contre un plan de montage d'un meuble en kit mal illustré ou pas assez détaillé, contre une information introuvable ?

Le manuel d'utilisation doit donc être

• utile : une information exacte, mais inutile, ne fait que renforcer le sentiment d'inutilité et gêne la recherche de l'information pertinente ;
• agréable : quant à la forme, la clarté (présentation, style), mais aussi en mettant en avant les préoccupations de l'utilisateur et non pas les caractéristiques techniques du produit.

Quelques questions préliminaires

On peut envisager trois situations :

• il s'agit d'un produit simple d'utilisation ;
• il s'agit d'un produit complexe, mais on veut restreindre les explications aux cas les plus simples, les cas complexes étant à la charge de spécialistes, (c'est par exemple le cas d'un manuel d'entretien d'une automobile où l'on explique comment vérifier le niveau d'huile, changer une roue ou les ampoules, mais les réparations plus complexes sont à la charge d'un garagiste ou d'un amateur éclairé) ;
• il s'agit d'un produit complexe dont l'utilisateur final doit tout connaître.

La première question à se poser est donc : « dans quelle situation se trouve-t-on ? »

Ensuite, il faut se poser la question des prérequis pour l'utilisation du produit. Cela va déterminer le niveau de détail des explications et le vocabulaire employé : faut-il en particulier définir les termes spécifiques, ou bien ceux-ci sont-ils considérés comme acquis ?

Par ailleurs, il faut connaître le statut légal du document, s'agit-il :

• d'un document obligatoire d'après la législation ou la réglementation ?
• d'un document contractuel (le contrat prévoit la fourniture de ce document) ?
• d'un document facultatif que l'on fournit pour être agréable à l'utilisateur (pour des raisons commerciales ou bien pour l'aider à utiliser un produit libre et gratuit) ou que l'on vend à part du produit (par exemple un manuel d'utilisation d'un logiciel qui n'est pas vendu avec celui-ci).

En cas d'obligation légale, réglementaire ou contractuelle, il faut connaître les termes de l'obligation pour s'y conformer. Il se pose également le problème de la langue dans laquelle on rédige. Dans le cadre d'une démarche qualité, il faut recueillir auprès des utilisateurs leurs attentes et avis sur la documentation, celle-ci suit un cycle d'amélioration continu.

Le type de document produit est également important : document papier imprimé (les contraintes d'un imprimeur sont différentes de celles d'une imprimante), fichier PDF à imprimer (il faut alors prendre en compte les ressources de l'utilisateur, par exemple ne pas vider ses cartouches d'encre avec des à-plat), fichier PDF à visualiser, fichiers HTML, aide Windows (HLP, CHM), … Si l'on fournit un document sous plusieurs formes, par exemple papier et aide en ligne, il faut envisager une solution de source unique (single sourcing).

Cela nécessite de connaître le mode de distribution et, dans le cas d'un objet matériel, du format de l'emballage (packaging) : la petite taille est parfois un argument de vente (pour un téléphone portable, pour un baladeur), d'un point de vue mercatique, cela est reflété par un emballage également de petite taille, ce qui limite la taille du document. À l'inverse, un téléviseur ou une imprimante laissent une grande latitude pour le format du document.

Enfin, il faut savoir

• qui va rédiger le manuel : de préférence une personne proche des utilisateurs, afin de connaître leur culture, leurs préoccupations, mais en relation avec l'équipe de conception ;
• à quel stade du projet on commence à rédiger : le manuel doit être prêt au moment de la sortie du produit, mais le produit doit être suffisamment proche de sa version finale pour que le manuel corresponde ;
  dans le cas d'un logiciel par exemple, la rédaction peut commencer sur la base du cahier des charges (spécifications) pour ce qui est des parties générales (présentation, mise en place des grandes parties), puis on l'affinera sur la base des versions bêta (la rédaction étant une occasion de tester les fonctionnalités, donc de déterminer le produit).

Les réponses à ces questions vont déterminer le format du manuel, l'épaisseur du livre ou le nombre d'écrans d'aide. Et cela va donc déterminer l'outil utilisé pour le créer : quel logiciel ? Un traitement de texte suffit-il ? Faut-il un logiciel de gestion de documentation ?

Quel type de manuel ?

On peut distinguer trois types de manuels :

• les manuels procéduraux : on explique pas à pas comment réaliser une opération ;
• les manuels pédagogiques : outre la description de l'utilisation, il est destiné à transmettre des connaissances plus globales, un savoir-faire ;
• les manuels de référence : toutes les fonctions, parties, … sont décrites par le menu.

Notons que l'on peut avoir un manuel en deux parties, ou bien deux manuels, un procédural, l'autre de référence.

Dans tous les cas, on a un manuel qui ne se lit pas comme un livre, page après page, mais en accédant directement à la partie utile (mise à part pour l'introduction). Le manuel doit donc disposer :

• d'une table des matières explicite et détaillée : en particulier, on intitule les sections en faisant référence au but poursuivi et non pas à la fonction utilisée ;
  par exemple, pour un manuel d'utilisation d'un traitement de texte, on n'appellera pas la section « Utilisation du menu Format » mais « Mise en forme du texte » ;
• d'un index permettant une recherche par mot-clef.

Manuel procédural

Un manuel de type procédural est un manuel pas à pas. Dans le cas d'un produit complexe, il ne va pas expliquer la totalité du produit, mais simplement les principales utilisations. Il faut pour cela commencer par identifier lesdites utilisations.

Ce type de manuel doit permettre à une personne de prendre en main le produit rapidement. Il est bien adapté pour une personne non qualifiée (opérateur ne maîtrisant pas la théorie sous-jacente à l'utilisation du produit), un débutant ou un travailleur intérimaire, un stagiaire, en cas de départ de la personne utilisant habituellement le produit. Les entreprises écrivent fréquemment des procédures, le manuel doit pouvoir servir de base à ce travail.

Il ne faut pas hésiter à répéter les informations : si une personne utilise le produit en ayant le manuel à la main, il est vite ennuyeux de devoir tourner les pages pour trouver une autre information, puis de revenir. Si une opération est présente dans plusieurs procédures, on ne fera pas de référence croisée (de type « voir la section 1.7 p. 28 »), l'opération sera donc écrite intégralement à chaque fois. Si le manuel est rédigé avec un logiciel de type MediaWiki, on pourra utiliser les modèles. Avec LaTeX, on pourra mettre l'opération dans une commande personnelle (voire dans un fichier spécifique).

Le manuel doit être abondamment illustré par des dessins ou des photographies clairs (pensez que certaines entreprises font des procédures sous forme de bande dessinée pour le personnel illettré).

Manuel pédagogique

Un manuel pédagogique est plutôt du type « incrémental » : c'est un manuel dans lequel on présente d'abord l'utilisation de manière générale, pour ensuite détailler certains points. Ce n'est plus exactement un manuel procédural, puisque l'on ne suit pas les opérations dans l'ordre. L'avantage d'un tel manuel est que lorsque l'on présente une opération détaillée, le lecteur la replace facilement dans le contexte et connaît la finalité de l'opération. Cela permet une meilleure compréhension, une meilleure assimilation.

Par exemple, pour un logiciel de traitement de données, on fait une première section présentant un traitement classique : chargement des données, traitement dans un cas simple, sauvegarde et impression du résultat. Ensuite, on va dans le détail : cas plus compliqués, paramètres ajustables, modification du format d'impression, ...

Dans ce type de manuel, on traitera d'exemples concrets, on proposera des exercices, éventuellement appuyés sur des didacticiels (« tutoriels »).

Par exemple, les règles vendues avec un jeu d'échecs sont certes complètes et pertinentes, mais ne permettent pas pour autant de progresser ; il faut pour cela avoir recours à un manuel pédagogique avec exemples et exercices.

On remarque que de plus en plus de logiciels dont la prise en main est relativement intuitive sont livrés sans manuel d'utilisation papier (mais toutefois avec une aide en ligne) mais on dispose de nombreux livres pédagogiques, à acheter en sus. Il suffit de regarder le rayon Microsoft Word ou Adobe Photoshop d'une librairie informatique.

Manuel de référence

Ce type de manuel se veut exhaustif. On va le parcourir de A à Z. L'organisation suit alors plus la logique du concepteur que celle de l'utilisateur : on liste les sous-ensembles un par un.

Par exemple, dans le cas d'un logiciel, on va prendre les barres de boutons une par une et décrire chacun des boutons, puis les menus un par un et décrire chacune des options, puis les boîtes de dialogue, …

Conseils de rédaction

Structure du manuel

Le manuel comporte typiquement plusieurs parties :

• la page de titre, ou pour les documents informatiques la page d'information, avec
  • titre : c'est ce qui interpelle le lecteur, faut-il mettre simplement « mode d'emploi » ou bien « comment utiliser votre … », « conseils d'utilisation », …
  • la référence au produit, et au(x) modèle(s) concerné(s) : numéro de version, date de création, …
  • la date de révision du manuel et/ou son numéro de version,
  • d'éventuelles mentions légales, notamment relatives au droit d'auteur et de reproduction, copyright,
  • l'adresse de l'organisme référent pour le document, organisme auquel on peut demander un nouvel envoi si le document est défectueux, ou des remarques et suggestions,
  • éventuellement nom de l'auteur du document ;
• la table des matières ; en typographie française, on place la table des matières à la fin de l'ouvrage, on peut alors mettre au début un sommaire (ne reprenant que les titres des chapitres et pas les titres des sections et sous-sections) ;
• introduction :
  • description rapide et globale du produit : à qui est-il destiné, à quoi sert-il ?
  • description de la finalité globale du manuel : pour qui a-t-il été rédigé, dans quel esprit, comment doit-on l'utiliser (lecture continue ou bien accès direct à une section) ?
  • explicitation des conventions : abréviations courantes, mises en forme spécifiques (par exemple pour un logiciel, les commandes tapées sont en polices à chasse fixe, les noms des boutons sont en gras, …) ;
• présentation générale : identification des grandes parties du produit et de leurs fonctions, mise en place du vocabulaire spécifique (par exemple pour un logiciel : qu'appelle-t-on un menu contextuel, une barre de tâches) ;
• texte proprement dit ;
• éventuellement des annexes ;
• un index.

Si des défauts, des non-conformités, des erreurs ou bogues ont été constatés, ils doivent être signalés. C'est une preuve de responsabilité et de maturité plus que de faiblesse (tout le monde sait que le zéro défaut est un objectif, pas une réalité) ; on songera par exemple à la liste des effets secondaires dans la notice d'un médicament…

D'un point de vue organisationnel, il vaut parfois mieux sortir un produit avec des erreurs connues et signalées, que faire des modifications de dernière minute sans les tester, ou bien que faire monter le prix ou retarder la livraison : un utilisateur peut avoir un besoin immédiat d'un produit imparfait et être prêt à fonctionner en mode « dégradé » en attendant un correctif. Cela ne doit cependant pas inclure des défauts de sécurité, et sans abus, car on risque de mécontenter l'utilisateur et d'entamer la réputation de l'organisation.

Style

On se méfiera du jargon technique, des anglicismes et néologismes. Est-il nécessaire pour un médecin de parler de « décubitus » pour la position allongée, pour un informaticien de dire d'une fonction qu'elle est « implémentée » pour développée/implantée ? Ce jargon non nécessaire sème le trouble dans l'esprit du lecteur, et on se rend souvent compte qu'il n'est pas clair non plus dans celui de l'auteur. Si un concept précis nécessite un terme précis, donc peu courant, il vaut mieux le définir qu'employer des termes obscurs à tort et à travers ; un bon réflexe consiste à essayer d'expliquer en mots plus simples, et en français, un mot spécifique employé.

« Ce que l'on conçoit bien s'énonce clairement,

Et les mots pour le dire arrivent aisément. »

Nicolas Boileau

Le style utilisé doit aussi prendre en compte la culture des utilisateurs : culture professionnelle, mais aussi culture nationale, notamment lorsque l'on écrit en langue étrangère. Penser aussi que les francophones ne sont pas tous français, mais aussi belges, suisses, québécois, sénégalais, … Par exemple, les manuels de rédaction technique anglophones recommandent, lorsque l'on représente des personnes, de ne pas se contenter d'hommes blancs, mais de représenter les deux sexes et différentes ethnies ; ils recommandent également d'alterner l'usage du masculin et du féminin pour désigner les personnes (voir aussi Politiquement correct).

La lecture d'un roman nécessite le plaisir de redécouvrir la richesse oubliée d'une langue. Au contraire un manuel doit être écrit dans une langue simple, pour être compris de tous, y compris de personnes étrangères, apprenant la langue.

Mise en forme

Document papier

Il convient d'adopter une mise en forme sobre et homogène ; on s'intéressera particulièrement à la notion de séparation du fond et de la forme.

Pour plus de détails voir : Du bon usage d'un traitement de texte.

Les manuels d'utilisation ont fréquemment recours aux notes de marge. L'avantage est que la note est située à côté du texte qu'elle commente, contrairement à une note de bas de page ou de fin de chapitre. Cela permet, par exemple, de mettre la représentation d'un objet (comme une pièce, un bouton graphique de l'interface d'un logiciel) : le dessin ne coupe pas le texte, il ne nuit pas à la continuité de lecture, mais on peut le trouver facilement. Il faut pour cela définir une marge importante pour le corps du texte, de 3 à 4 cm en plus de la marge classique (par exemple, les titres et les notes de marge sont à 2 cm du bord et le corps du texte à 5 ou 6 cm).

Avec LaTeX, on utilisera

• pour définir les marges : dans le préambule, avec l'extension geometry, la commande \geometry{textwidth=longueur,rmargin=longueur} pour les marges extérieures, ou \geometry{textwidth=longueur,lmargin=longueur} pour les marges intérieures ;
• la commande \marginpar{note}, en chargeant éventuellement les extensions mparhack, manfnt si le placement se fait mal.

Avec un traitement de texte classique, on peut utiliser pour les notes de marge un tableau à deux colonnes sans filet (trait) : la colonne de gauche est dans la marge et contient les notes, la colonne de droite contient le texte.

Les notes de marge sont fréquemment utilisées pour mettre des symboles attirant l'attention du lecteur sur le point détaillé dans le texte ou indiquant le statut du texte (par exemple : indication de sécurité, opération délicate).

Il faut adopter une présentation aérée, avec des grandes marges, et changer de page entre chaque sujet, afin d'éviter les confusions et de permettre de retrouver facilement une information.

Document électronique

Il faut impérativement éviter les défilements horizontaux : il convient donc de contrôler la dimension d'affichage des images et des divers objets (tableaux par exemple) par rapport à la résolution des écrans. Il faut considérer que les écrans et cartes graphiques des utilisateurs ne sont pas forcément aussi performantes que ceux de l'auteur.

On évitera également les défilements verticaux : on s'arrangera pour que chaque page fasse une hauteur d'écran (même remarque que ci dessus).

On peut utiliser des éléments surgissant, de type pop-up ou tooltip ; en HTML, on peut utiliser un titre (par exemple <span title="message">objet</span>), ou une pseudo-classe dynamique (:hover, :active ou :focus), ou bien du JavaScript.

Le format d'aide Windows 95 (WinHelp 4.0) possède des fonctionalités d'objets surgissants, mais d'une part ce format est spécifique à la plateforme Windows et n'est donc pas portable, et d'autre part il n'est plus supporté par Windows Vista. Le format CHM (Microsoft Compressed HTML) est du HTML, il est donc plus facilement transposable.

L'objet surgissant (image ou texte) devrait être de taille réduite, par exemple l'équivalent d'une note (note de bas de page ou note de marge).

Le document doit posséder une page d'index ou un outil permettant une recherche par mot-clef.

Spécificité de la source unique

La source unique, ou single sourcing, présente l'avantage de ne maintenir qu'un seul fichier au lieu de deux. Par contre, les contraintes des deux formats — papier et aide en ligne ou page HTML — sont différents, on ne les lit pas de la même manière. Il faut donc disposer d'un outil performant.

Parmi les solutions, on peut envisager :

• LaTeX, en transformant le document en HTML avec latex2html ou tex4ht ;
• une solution de type wiki, générant du HTML et un format imprimable (éventuellement du LateX) ;
• une solution propriétaire, de type Microsoft Word associé à Doc-To-Help de Component One ;
• du PDF avec des liens hypertextuels, permettant une utilisation simple à l'écran.

La principale difficulté consiste à prévoir les incompatibilités :

• certaines mises en forme ne sont adaptées qu'à un type de support ; par exemple,
  • sur format papier, on pourra utiliser une image flottante, alors que sur format électronique, on la placera après le paragraphe concerné,
  • les notes de marge sont spécifiques au format papier,
  • les éléments surgissant (pop up, tooltip) sont spécifiques au format électronique ;
• la taille et la résolution des images ne se règlent pas de la même manière ;
• les documents papier utilisent des références croisées de type « voir section 1.7 p 28 », tandis que les documents électroniques utilisent des liens hypertextuels ;
• si deux sections d'un livre s'enchaînent, elles sont sous la forme de deux pages HTML distinctes ; il peut être nécessaire de rappeler des éléments (redondance), puisque l'on peut accéder directement à la deuxième page sans passer par la première.