Conseils de rédaction technique (suite)

Capture Microsoft Word

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.(...)

(...)
Paiement en ligne
Avantages
a) Réduction des frais d'exploitation
Le paiement en ligne réduit les frais d'exploitation, car aucun caissier n'a besoin d'être impliqué dans les transactions.

b) Augmentation de la disponibilité du service
Le paiement en ligne est offert 24 heures sur 24. Les heures d'ouverture prolongées peuvent engendrer plus de ventes.

c) Réduction de l'inventaire
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 :

Nom du champ Type Longueur Obligatoire Lecture seule Description
Pays Liste s.o. Oui Non Il permet au nouveau membre d'identifier le pays dans lequel il habite. Par défaut, le pays sélectionné correspond à celui associé l'adresse IP de son fureteur. La liste des pays provient du domaine de valeur Pays et est triée par ordre alphabétique. Si aucune valeur n'est sélectionnée à l'enregistrement du formulaire, afficher le code de message #004 (champ obligatoire).
Courriel Texte 150 Oui Non Il permet à l'entreprise de communiquer avec le nouveau membre à l'aide de l'adresse que ce dernier fournit. Par défaut, le champ est vide. Lorsque l'adresse courriel n'est pas fournie, afficher le code de message #004 (champ obligatoire). Lorsque l'adresse courriel n'a pas été saisie correctement, afficher le code de message #021 (format courriel).

Nom du champ Spécification Description
Pays .Type Liste déroulante
.Description Permet au nouveau membre d'identifier le pays dans lequel il habite.
.Actif Saisissable en tout temps
.ValeurDéfaut Correspond au pays associé l'adresse IP du fureteur du membre.
.SourceListe Provient du domaine de valeur Pays.
.Tri Par ordre alphabétique.
.ValiderObligatoire Si aucune valeur n'est sélectionnée à l'enregistrement du formulaire, afficher le code de message #004 (champ obligatoire).
Courriel .Type Champ texte
.Description Permet à l'entreprise de communiquer avec le nouveau membre à l'aide de l'adresse fournie par ce dernier.
.LongueurMax 150 caractères
.Actif Saisissable en tout temps
.ValeurDéfaut Vide
.ValiderObligatoire Lorsque l'adresse n'est pas fournie, afficher le code de message #004 (champ obligatoire).
.ValiderFormat Lorsque l'adresse courriel n'a pas été saisie correctement, afficher le code de message #021 (format courriel).

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 est 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é.

Lorsque l'utilisateur clique sur le bouton soumettre, une confirmation est demandée (message GEN0182):
  • Dans l'affirmative, le formulaire est envoyé et l'utilisateur est redirigé vers la page d'accueil.
  • Dans la négative, le formulaire n'est pas soumis et l'utilisateur demeure dans la page de demande de service. Le formulaire n'est pas effacé.

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.

  • Utilisez un gabarit simple d'utilisation, pour la documentation à l'aide d'un traitement de texte;
  • Favorisez l'utilisation d'un outil de documentation au lieu d'un traitement de texte;
  • Prenez le temps de bien connaître votre logiciel vous permettant de documenter.

17. Définir une convention typologique

Une convention typologique 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 typologique, 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 typologique est définie dans un petit document qui explique ces règles de documentation.

Étape 1, Obtenir l'identifiant du billet
Lorsque l'utilisateur clique sur le bouton "Détail" dans le système TicketRun, la page web lançant ce traitement est appelée avec un paramètre fourni dans l'URL. Ce paramètre est nommé ticketid correspond à l'identifiant du billet.

Étape 2 - Obtenir les informations du billet
Les informations du billet sont obtenues à l'aide du service E12.2 Obtenir le billet. Ce service requiert un identifiant ticketid fourni par le système TicketRun obtenu à l'étape précédente.(...)

Étape 1 - Obtenir l'identifiant du billet
Lorsque l'utilisateur clique sur le bouton Détail dans le système TicketRun, la page web lançant ce traitement est appelée avec un paramètre fourni dans l'URL. Ce paramètre est nommé ticketid correspond à l'identifiant du billet.

Étape 2 - Obtenir les informations du billet
Les informations du billet sont obtenues à l'aide du service E12.2 Obtenir le billet. Ce service requiert un identifiant ticketid fourni par le système TicketRun obtenu à l'étape précédente.(...)

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.

Commentaires

Avatar par défaut
Ajouter un commentaire

Nouveau commentaire

Nom ou pseudonyme

Courriel (Associer votre courriel à une image avec Gravatar)

Commentaire