Conseils de rédaction technique (suite)

Organisation

10. Séparer et structurer les contenus longs

Évitez de rédiger de longs paragraphes, car il est difficile pour le lecteur de trouver rapidement l'information dont il a besoin. Découpez le texte en paragraphes plus petits et ajoutez des titres à ces paragraphes. Les titres permettent de savoir ce que contient le texte sans avoir besoin de le lire, ce qui rend le travail de recherche plus facile pour le lecteur. Lorsque le contenu s'y prête, hiérarchiser l'information avec différents niveaux de titre peut aussi aider à la lecture.

Contre-exemple et exemple :

(...)
Le module de paiement en ligne offre plusieurs avantages à la ligne d'affaires. Premièrement, il réduit les frais d'exploitation, car aucun caissier n'a besoin d'être impliqué dans les transactions. Deuxièment, le paiement en ligne est offert 24 heures sur 24. Les heures d'ouverture prolongées peuvent engendrer plus de ventes. Troisièment, certains articles peuvent provenir directement du fournisseur et être livrés directement aux clients sans avoir eu besoin de détenir l'article en stock.(...)

11. Utiliser adéquatement les tableaux

L'utilisation des tableaux permet de structurer l'information. Par contre, ceux-ci ne doivent pas comporter trop de colonnes, car l'information devient difficile à comprendre. Surtout si l'information contenue dans les cellules est du texte descriptif. Mieux vaut favoriser le nombre de rangées d'un tableau que son nombre de colonnes.

Contre-exemple et exemple :

12. Gérer les renseignements complémentaires

Les informations à présenter dans un document n'ont pas toutes le même niveau d'importance. Les niveaux de titre et la disposition du contenu permettent de mettre en évidence les informations importantes par rapport à celles qui le sont moins.

Les renseignements complémentaires sont des informations qu'il faut présenter afin que le document soit suffisamment précis. Parfois, ces précisions ont de l'importance. D'autres fois, moins. Les techniques pour présenter les renseignements complémentaires sont:

• Utilisatation d'une note, lorsque le renseignement complémentaire est important :
  (...) Chaque mois le système doit détecter s'il y a présence ou non d'un versement de subvention. Lorsqu'il y a versement, les autorisations en attente sont débloquées (...)

  ---

  Note : Le versement des subventions s'effectue le premier jour de chaque trimestre de l'année financière de l'organisme subventionnaire.

  ---

• Utilisation d'une référence en bas de page, lorsque le renseignement n'est pas essentiel à la compréhension générale :
  L'avis de versement est produit pour une période donnée1. Pour cette période, l'avis doit contenir le nombre d'employés, la rémunération brute et le montant des retenues d'impôt à la source.
  ---------
  1. Récurrence mensuelle ou trimestrielle.
• Utilisation d'une référence à un annexe, lorsque les renseignements sont volumineux et n'ont pas leur pertinence à même le texte :
Le taux d'imposition est établi selon le salaire et peut varier d'une année à l'autre. Le système doit gérer les différents paliers d'imposition par période donnée. Voir la table d'imposition 2015 à l'annexe F à titre d'exemple.

Précision

13. Employer un ton neutre

Évitez de parler à la première personne (je ou nous). On s'attend à ce qu'un document technique soit rédigé de manière impersonnelle. De plus, l'auteur du texte ne doit pas émettre d'opinion, ne serait-ce qu'en ajoutant un simple qualificatif.

La fonction très conviviale de copie sert à dupliquer le contenu sélectionné. Je crois que les utilisateurs seront satisfaits de la rapidité de l'opération.

La fonction de copie sert à dupliquer le contenu sélectionné. Elle a pour objectif de rendre cette opération simple et efficace pour l'utilisateur.

14. Détecter et préciser les "flous"

Lorsque l'on rédige des spécifications fonctionnelles, il est possible que celles-ci ne soient pas assez précises. Dans cette situation, une spécification peut porter à interprétation ou causer des défaillances. Pour remédier à la situation, il est bon de se mettre dans la peau du lecteur, c.-à-d. le valideur affaires, le programmeur ou le testeur afin de vérifier si toute l'information dont ils ont besoin est présente.

Lorsque l'utilisateur clique sur le bouton soumettre, une confirmation est demandée. Dans l'affirmative, le formulaire est envoyé.

15. Utiliser les termes exacts

Il est important de choisir les termes employés par le lectorat (parties prenantes). Si pour vous le système traite des bons de commande, mais que le client utilise le terme devis, utilisez son vocabulaire afin d'être certain de bien vous comprendre.

Demandez des définitions, car il y a parfois des subtilités à maitriser. Par exemple, quelle est la différence entre les termes Salaire et Rémunération? Créez et maintenez un glossaire auquel vos documents pourront référer.

On ne rédige pas un document technique de la même manière que l'on écrirait une histoire. Il n'y a pas de problème en rédaction technique de répéter plusieurs fois le même mot pour dire la même chose, s'il s'agit du mot exact. Évitez d'être créatif sur ce point et évitez l'utilisation des synonymes.

Cohérence

16. Appliquer les mêmes styles au sein d'un même document

On voit parfois des dossiers fonctionnels qui ont près d'une dizaine d'années et qui ont été maintenus par différentes personnes au fil du temps. Ces dossiers, rédigés dans des logiciels de traitement de texte, ont bien souvent mal vieilli. Par exemple, il y a des titres en gras, mais ceux-ci ne sont pas référencés dans la table des matières. Parfois, le texte a une taille de 11pt, d'autres fois 10pt. Les marges varient d'une section à l'autre. Ce sont des détails, mais s'il y en a beaucoup, il devient difficile de suivre le fil du document.

17. Définir une convention typographique

Une convention typographique est un ensemble de styles appliqué à des mots, phrases ou expressions de même nature dans un document. Cette convention, une fois définie, doit être appliquée à l'ensemble du document et idéalement doit aussi correspondre à celle utilisée par l'organisation.

Dans une convention typographique, on définit dans quel contexte on applique du gras, de l'italique, etc. De plus, on peut indiquer comment doivent être présentés les figures, les tableaux, etc. Une convention typographique est définie dans un petit document qui explique ces règles de documentation.

18. Soignez l'orthographe

Dans un contexte de production, où la documentation doit avancer rapidement, il peut arriver que l'orthographe soit négligée. Mais puisque les écrits restent, il est bon de faire une relecture et utiliser au besoin des logiciels de correction orthographique tels qu'Antidote.

Les fautes d'orthographe peuvent distraire les lecteurs qui les trouvent

Pas évident de conprendre un text plein de faute. Ça accroche le lecteur pis le rend moins vite.

Il n'est pas évident de comprendre un texte bourré de fautes. Celles-ci irritent le lecteur et ralentissent sa lecture.