Conseils de rédaction technique
Les conseils de rédaction technique s'appliquent parfaitement à la documentation fonctionnelle. Ce type de rédaction a pour objectif la clarté, la concision, l'organisation, la précision et la cohérence afin de faciliter les tâches que devra entreprendre le lectorat auquel est destiné le dossier fonctionnel. Ces tâches sont principalement des activités de révision, de programmation, de préparation d'essais, et évolution du système décrit.
Les exigences et les comportements logiciels doivent être présentés dans la documentation fonctionnelle selon les principes suivants.
Clarté
1. Rédiger au présent
Un document rédigé au passé donne l'impression au lecteur que l'information n'est peut-être plus utile. Au futur, il peut y avoir confusion à savoir si ce qui est décrit existe ou non. L'utilisation du temps présent évite toute ambiguïté.
Contre-exemple et exemple :
En cliquant sur le bouton Consulter, le dialogue de détail du produit apparaîtra.
En cliquant sur le bouton Consulter, le dialogue de détail du produit apparait.
2. Utiliser la forme positive
De manière générale, il est préférable d'employer la forme positive pour décrire une condition ou une règle fonctionnelle. La forme positive facilite la compréhension. Les doubles négations sont à proscrire.
Contre-exemple et exemple :
L'article dont le statut n'est pas publié n'est pas présenté dans le catalogue.
Seuls les articles dont le statut est publié sont présentés dans le catalogue
3. Éviter les énumérations linéaires
Les énumérations à même un paragraphe ajoutent de la lourdeur au texte. Il est préférable d'utiliser les listes, celles-ci rendent la présentation du texte plus clair.
Contre-exemple et exemple :
Une fois authentifié, le système attribut le rôle à l'utilisateur connecté. L'utilisateur possède soit le rôle d'administrateur, d'administrateur délégué, de gestionnaire, de contrôleur, ou d'adjoint.
- Administrateur;
- Administrateur délégué;
- Gestionnaire;
- Contrôleur;
- Adjoint.
4. Numéroter les listes
Au-delà de sept (7) éléments par liste, il est bien de numéroter les éléments d'une liste et cesser l'utilisation de puces. Ceci facilite la communication.
Contre-exemple et exemple :
Jean et Sophie regardent une longue liste de conditions identifiées par des puces. Sophie dit : « C'est écrit à la cinquième condition en partant de la fin. »
Jean et Sophie regardent une longue liste de conditions identifiées par des numéros. Sophie dit : « C'est écrit à la condition numéro 34. »
5. Numéroter les étapes
S'il s'agit d'une liste d'étapes séquentielles, mieux vaut d'emblée numéroter les étapes. Ceci permet de comprendre l'existence d'un ordre. Il est bien que chaque étape distincte ait son numéro.
Contre-exemple et exemple :
- Accéder au formulaire de transfert;
- Télécharger son fichier;
- Soumettre, puis obtenir son numéro de confirmation;
- Accéder au formulaire de transfert;
- Télécharger son fichier;
- Soumettre le formulaire;
- Obtenir son numéro de confirmation.
6. Éviter les majuscules
Il est plus difficile pour l'oeil humain de lire rapidement un texte lorsqu'il est écrit en majuscule. Cette difficulté réside dans le fait que les lettres de chaque mot ont toutes la même hauteur. Le texte en majuscule ne doit pas servir à écrire des avertissements ou des informations importantes. Mieux vaut utiliser un style et une présentation qui met en évidence l'information importante.
Contre-exemple et exemple :
LA FONCTIONNALITÉ DE SUPPRESSION DE COMPTE SUPPRIME TOUTES LES DONNÉES ASSOCIÉES AU COMPTE. ELLE NE DOIT ÊTRE ACCESSIBLE QUE PAR L'ADMINISTRATEUR DE SYSTÈME.
Avertissement!
La fonctionnalité de suppression de compte supprime toutes les données associées au compte. Elle ne doit être accessible que par l'administrateur de système.
7. Éviter de souligner
Afin d'éviter toute confusion avec l'hyperlien, éviter d'appliquer le style souligné. Utiliser un autre style ou une autre présentation pour mettre en relief l'information désirée.
Contre-exemple et exemple :
La longueur associée au code utilisateur et le format d'adresse courriel sont validés au moment de soumettre le formulaire.
- Longueur associée au code utilisateur;
- Format de l'adresse courriel.
Concision
8. Ne pas surcharger le texte
Soyez concis, évitez de surcharger le texte d'adverbes ou de contenus implicites, voire inutiles. Il est important de se demander si les mots choisis apportent de la valeur à la compréhension du lecteur.
Contre-exemple et exemple :
Conformément aux attentes, lorsque l'utilisateur clique à l'aide de la souris sur le bouton Imprimer présent dans la page, l'impression démarre immédiatement.
Lorsque l'utilisateur clique sur le bouton Imprimer, l'impression démarre.
9. Faire des phrases courtes
Tentez de produire des phrases courtes. Chaque phrase devrait représenter idéalement qu'une seule idée. Pour se faire, scindez les phrases longues. Utilisez les verbes à l'infinitif pour alléger les phrases.
Contre-exemple et exemple :
Lorsque l'utilisateur clique sur le bouton Soumettre, il faut conserver en session les données du formulaire afin de produire le courriel destiné à l'administrateur à partir de celles-ci.
Clique du bouton Soumettre:
Conserver les données du formulaire en session. Celles-ci serviront à produire le courriel destiné à l'administrateur.
