Norme de rédaction de la documentation
Rédigez la documentation M-Press en anglais technique contrôlé, axé sur les tâches.
La documentation M-Press utilise un style maison basé sur ASD-STE100. Il s’agit d’une norme de rédaction de projet. Ce n’est pas une déclaration de conformité formelle à ASD-STE100.
Choisissez un type de document
Chaque page doit satisfaire un besoin principal du lecteur:
| Type | Besoin du lecteur | Contenu |
|---|---|---|
| Tutoriel | Apprendre en faisant | Un parcours complet et reproductible |
| Guide pratique | Réaliser une tâche | Étapes directes pour un résultat défini |
| Référence | Trouver des faits pendant le travail | Descriptions complètes et cohérentes |
| Explication | Comprendre un sujet | Raisons, contexte et compromis |
Ne mettez pas de longues explications dans une procédure. Mettez un lien vers une page d’explication.
Utilisez l’anglais technique contrôlé
Appliquez ces règles:
- Utilisez un terme pour un concept.
- Utilisez un mot qui n’a qu’un seul sens dans une phrase.
- Utilisez la voix active lorsque l’acteur est important.
- Utilisez l’impératif pour une instruction.
- Mettez une seule action par instruction.
- Placez la condition avant l’action qui en dépend.
- Conservez des phrases courtes. Scindez une phrase si elle contient deux faits indépendants.
- N’utilisez pas de pronoms vagues tels que it ou this lorsque le nom n’est pas clair.
- N’utilisez pas d’idiomes marketing, de plaisanteries ou d’expressions spécifiques à une culture dans une procédure.
- Placez un avertissement avant toute action pouvant causer des dommages ou une perte de données.
Les noms de produits, les noms de commandes, les clés de configuration et les termes techniques nécessaires constituent le vocabulaire approuvé du projet. Définissez un terme inconnu lors de sa première utilisation.
Rédigez des procédures testables
Indiquez le prérequis, l’action et le résultat attendu. Utilisez des commandes exactes. Utilisez un seul chemin pris en charge dans un tutoriel. Mettez les alternatives dans un guide pratique.
Après avoir rédigé une procédure, exécutez-la dans un environnement propre. Vérifiez chaque lien et exemple de code. Si le résultat a une interface utilisateur, vérifiez-la aux largeurs bureau et mobile.