Ce qu’il faut éviter en rédaction technique

Voici quelques exemples de choses à éviter lorsque l’on rédige une documentation technique.

 

N’écrivez pas d’informations superflues

L’idéal, même si cela reste difficile à mettre en œuvre, est de construire une documentation bannissant toute forme d’information superflue. Lorsque vous écrivez sur une fonctionnalité ou une interface, restez focalisé sur cette interface et ne dérivez pas vers la description d’une fonction annexe par exemple. Si cela est nécessaire, faites un renvoi vers la section concernée via un lien.

Ne parlez pas de ce qui pourrait arriver, ou de ce qu’il est possible de faire. Dites ce que l’utilisateur doit faire et décrivez les résultats visibles et identifiables. S’il existe des variantes, sélectionnez la plus commune et faites un lien vers les autres.

 

Ne présumez pas des connaissances de l’utilisateur

L’une des compétences principales d’un rédacteur technique est la capacité de se mettre à la place de l’utilisateur pour laquelle nous écrivons une documentation. Il existe cependant un piège à éviter : présumez des connaissances et des acquis du lecteur. Si certaines choses peuvent sembler évidentes pour le rédacteur, rien n’indique qu’elles le sont effectivement pour l’ensemble du public visé. C’est aussi vrai dans l’autre sens, un élément qui vous paraît complexe peut au contraire être tout à fait acquis pour celui qui vous lit. Il faut essayer de viser au milieu : imaginer un utilisateur ni trop ignorant, ni trop expérimenté. Le plus difficile étant d’identifier une évidence réelle d’une fausse évidence.

 

Ne noyez pas votre documentation sous les captures d’écrans

Les captures d’écran sont utiles lorsqu’elles apportent une valeur ajoutée au texte. Elles permettent aussi d’aérer la documentation et d’éviter les gros blocs de texte. Elles sont notamment utiles pour identifier des éléments dans des interfaces complexes ou pour illustrer des tutoriels. Dans des documentations de types « Guide utilisateur », Il faut faire attention à ne pas mettre des captures d’écran pour tout et n’importe quoi. Un texte bien écrit est souvent plus utile qu’une capture montrant un menu New > User. Du point de vue de la  maintenance de la documentation, avoir une documentation comportant des centaines de captures peut devenir problématique en cas de changement d’interface. Il faudra alors potentiellement mettre à jour de nombreux documents.

Si l’on se place dans l’optique d’une documentation contextuelle, les captures d’écran sont à bannir, l’interface se trouvant sous les yeux de l’utilisateur.

 

N’utilisez pas les liens de façon abusive

Tout comme les captures d’écran, les liens sont utiles pour renvoyer vers des sections connexes. Cependant, une documentation saturée de liens, au lieu de compléter l’information recherchée par l’utilisateur provoquera l’effet inverse. Le lecteur se perdra dans la structure documentaire, surtout si la navigation n’est pas optimale. Utilisez donc les liens avec parcimonie, dans une section dédiée de vos documents. Vous pouvez par exemple créer une section « Sujets associés », « Voir aussi » ou « Sur le même sujet ». Vous pouvez aussi réorganiser votre mise en page, et optimiser l’arbre de navigation.