Mauvais conseil: comment rédiger la documentation technique? Troisième partie et dernière

Conseils pour rédiger avec compétence la documentation technique pour les utilisateurs.
Partie 3 (finale)

La conclusion du manuel de notre rédacteur technique Andrei Starovoitov , qui vous aidera à rendre votre documentation utilisateur plus facile et plus compréhensible.



Cette fois, nous examinerons plus en détail:

• sujets conceptuels (pages de concept);
• sujets de référence (pages de référence);
• des sujets qui expliquent comment résoudre un problème (pages de dépannage);
• où et comment utiliser les captures d'écran;
• et donne également quelques conseils à ceux qui écrivent de la documentation en anglais.

Parties précédentes: notre approche de la documentation et de la localisation; conseils de documentation partie 1 et partie 2 .

Thèmes conceptuels (pages de concept)

Ces rubriques sont nécessaires pour fournir aux utilisateurs des informations techniques supplémentaires et ainsi ne pas surcharger la rubrique de tâche.

Veuillez noter qu'ils doivent contenir exactement des informations supplémentaires, mais pas un moyen de résoudre le problème.

Les sujets conceptuels sont bons à utiliser pour:

• expliquer comment fonctionne un processus particulier;
• Décrivez les nouvelles fonctionnalités ajoutées dans cette version du produit;
• fournir à l'utilisateur des informations supplémentaires qui l'aideront à prendre une décision;
• Dites ce que l'utilisateur peut faire dans votre application.

Par exemple, la rubrique «À propos des machines virtuelles» peut décrire ce que c'est et comment cela fonctionne. Mais cette rubrique ne doit pas contenir d'instructions sur la création d'une machine virtuelle - cela doit être décrit dans la rubrique de tâche.

Ainsi, un utilisateur expérimenté, en lisant un sujet de tâche, ne se plaindra pas: "Pourquoi me peignez-vous ce que c'est, je sais déjà ...". Et ceux qui ne connaissent pas verront un lien vers un sujet conceptuel et liront.

En général, les en-têtes de sujet conceptuels commencent par:

• «À propos de (quelque chose)» («À propos des machines virtuelles»);
• "Qu'est-ce que ...?" («Qu'est-ce qu'une machine virtuelle?»);
• "Comment ça marche (quelque chose)?" («Comment fonctionne une machine virtuelle?»);
• «Comprendre les bases des machines virtuelles», etc.

Voici un exemple d'un sujet conceptuel de la documentation anglaise:



Thèmes de référence (pages de référence) :

Ces rubriques décrivent diverses informations de référence auxquelles l'utilisateur peut se référer si nécessaire.

De bons exemples de tels sujets sont:

• «Glossaire» à la fin du guide;
• une rubrique dans laquelle vous décrivez quels éléments sont disponibles dans le menu et ce qu'ils font, quels raccourcis clavier vous pouvez utiliser lorsque vous travaillez avec le programme, quelles icônes sont disponibles dans la barre des tâches, etc.

Voici un exemple de rubrique décrivant les icônes de l'interface graphique:



Rubriques décrivant comment résoudre un problème (pages de dépannage)


Ces sujets aident l'utilisateur à surmonter un obstacle ou à résoudre un problème. Les rubriques de dépannage peuvent présenter les scénarios suivants:

• L'utilisateur a un problème et veut le résoudre. Par exemple, «Mon périphérique USB ne fonctionne pas sur une machine virtuelle».
• L'utilisateur a tenté de faire quelque chose et a échoué. Par exemple, «Je ne peux pas activer Parallels Desktop» («Je ne peux pas activer Parallels Desktop»).
• Il y a une condition ou une condition que l'utilisateur veut changer. Par exemple, «Windows est lent» («Windows semble lent»).

Qu'est-ce que c'est et ce n'est pas le dépannage :

Si l'utilisateur veut faire quelque chose, mais ne sait pas comment, cela doit être décrit non pas dans le dépannage, mais dans la rubrique de tâche.

Le dépannage implique que l'utilisateur a essayé de faire quelque chose (selon les instructions de la rubrique de tâche), mais il y a eu un problème et l'utilisateur ne sait pas comment le résoudre.

Par exemple, une rubrique qui décrit comment utiliser un lecteur externe dans un système d'exploitation invité est une rubrique de tâche.

Et le sujet qui décrit les problèmes possibles - «J'ai des problèmes pour connecter un disque dur» - est un sujet de dépannage. Son contenu implique que l'utilisateur a suivi les instructions, mais pour une raison quelconque, il n'a pas réussi.

Si vous écrivez une rubrique de tâche et qu'une étape des instructions peut entraîner de légères difficultés, il est autorisé de la décrire dans la même étape ou rubrique. Pour les difficultés mineures, il n'est pas nécessaire d'écrire une rubrique de dépannage distincte.

Par exemple, à la fin de la rubrique qui décrit comment modifier les raccourcis clavier, vous pouvez ajouter: «Certaines combinaisons de touches ne peuvent pas être modifiées ou supprimées».

Rubriques de dépannage

En règle générale, les rubriques de dépannage ont une structure similaire aux rubriques de tâches.

Ils consistent en:

• Titre («titre»)
• Partie introductive («intro»)
• Phrase introductive, après laquelle les étapes numérotées ou les informations nécessaires («en-tête d'étape») commencent
• Informations nécessaires pour résoudre un problème («étapes vers la solution»)
• La dernière partie («outro»)

Titre (titre de la page)

C'est bien lorsque l'en-tête de la rubrique de dépannage exprime le problème à la première personne de l'utilisateur. Par exemple:

• «Je ne peux pas activer Parallels Desktop» («Je ne peux pas activer Parallels Desktop»)
• «Windows est lent» («Windows semble lent»)
• «Un message indique« Aucune machine virtuelle détectée »» s'affiche

Si vous écrivez de la documentation en anglais, vous devez utiliser une majuscule de style titre dans le titre (pour la capitalisation, voir les détails à la fin de l'article):

À droite: mon périphérique USB ne fonctionne pas

Mauvais: mon périphérique USB ne fonctionne pas

Introduction (intro)

Immédiatement après l'en-tête, fournissez aux utilisateurs les informations dont ils ont besoin en premier.

Par exemple:

• Expliquez la cause la plus probable du problème. S'il peut y avoir plusieurs raisons, décrivez toutes les possibilités.
• Parfois, vous pouvez décrire en termes généraux ce qui doit être fait pour résoudre un problème. C'est en général - des instructions détaillées doivent être données dans les étapes de la solution.

Phrase introductive (en-tête d'étape)

Avant la séquence d'étapes que vous devez suivre pour résoudre le problème, écrivez une phrase d'introduction. N'oubliez pas de mettre un deux-points à la fin.

Si la solution au problème est une série d'actions séquentielles:

Dans de tels cas, la phrase d'introduction doit être faite selon les mêmes principes que pour les sujets de tâche (voir la deuxième partie des conseils), à savoir, utiliser les mêmes mots que dans la formulation de la tâche.

Par exemple, vous écrivez une rubrique de dépannage dans laquelle vous expliquez pourquoi l'utilisateur ne peut pas ouvrir la configuration de la machine virtuelle (l'élément de menu est grisé et inactif):

Titre: «Je ne peux pas ouvrir les paramètres de la machine virtuelle»

Introduction: «Si vous ne pouvez pas ouvrir les paramètres de la machine virtuelle (l'élément de menu est grisé), la raison la plus probable est que la machine virtuelle n'est pas désactivée.»

De plus, la phrase introductive: «Pour ouvrir les paramètres de la machine virtuelle:» (les mêmes mots sont utilisés dans cette phrase que dans la formulation de la tâche à effectuer)

Et puis il y a des étapes - 1) Assurez-vous que la machine est éteinte. Si cela fonctionne, cliquez ici et là. 2) Faites ensuite cela.

Si le problème a plusieurs solutions:

Dans de tels cas, la phrase introductive doit contenir les mots:

- «essayez ces solutions»,
- «essayez ce qui suit»,
- «assurez-vous que», etc.

Voici quelques exemples de la documentation anglaise:

Titre de la page: Je ne peux pas activer Parallels Desktop
Couvertures de tâches: une liste de choses à vérifier
En-tête d'étape: Si vous rencontrez des problèmes pour activer Parallels Desktop, assurez-vous que ...

Titre de la page: Windows semble lent
Couvertures de tâches: une liste de choses à essayer
En-tête d'étape: si les performances de Windows semblent lentes, essayez ce qui suit ...

Titre de la page: Un message dit «Aucun Mac connecté»
Couvertures de tâches: plusieurs choses à vérifier ou à essayer
En-tête de l'étape: si vous ne voyez pas votre Mac dans la liste des Mac

Informations nécessaires pour résoudre le problème (étapes de la solution)

Cette section comprend tout ce que l'utilisateur doit savoir et / ou entreprendre.

S'il existe plusieurs solutions:
Dans de tels cas, décrivez chaque méthode à l'aide de puces (plus d'informations à ce sujet dans la deuxième partie des conseils). Si une méthode est compliquée et que vous l'avez déjà décrite en détail dans une autre rubrique, donnez simplement un lien.

Si ce que vous devez faire est déjà décrit quelque part dans une autre rubrique:
Donnez simplement un lien vers ce sujet.

S'il n'y a pas d'instructions spécifiques, que pourrait-on faire pour résoudre le problème:
Fournissez toutes les informations supplémentaires qui peuvent aider l'utilisateur à comprendre ce qui pourrait être à l'origine du problème.

Conclusion (outro)

En conclusion, vous pouvez fournir des informations supplémentaires relatives à la tâche ou des solutions possibles au problème. Vous pouvez en savoir plus sur l'utilisation d'Outro dans la deuxième partie des conseils .

Utilisation de graphiques (captures d'écran, graphiques, diagrammes, etc.)

Les captures d'écran et les diagrammes peuvent aider les utilisateurs à mieux comprendre ce qui est écrit dans le sujet.

Quand utiliser des graphiques:

À chaque étape, vous n'avez pas besoin d'insérer une capture d'écran - l'utilisateur ne saura simplement pas où chercher, comparant constamment l'écran et la capture d'écran.

Les captures d'écran doivent être insérées lorsqu'elles aident de manière significative à comprendre ce qui est écrit dans les instructions.

Par exemple:

• Lorsque vous devez afficher un bouton ou une icône qui n'a pas de nom dans le gua, ou qui ne frappe pas immédiatement l'œil, ou il y en a plusieurs similaires à l'écran;
• Lorsque vous devez fournir un contexte pour la tâche ou une explication visuelle claire de comment et à quoi elle ressemblera à la fin;
• Si la capture d'écran vous permet de comprendre ou d'expliquer rapidement quelque chose qui nécessitera une explication trop longue et compliquée en mots.

Où et comment placer l'horaire:

Vous trouverez ci-dessous quelques recommandations sur l'emplacement et la manière de placer des graphiques sur la page.

1) Si la capture d'écran reflète les informations conceptuelles ou le résultat de la tâche, vous pouvez l'insérer dans ou après l'intro.

Voici un exemple tiré de la documentation anglaise, qui présente une rubrique décrivant le mode fenêtré de Windows. Une capture d'écran qui montre ce qui se passera après qu'un tel commutateur soit inséré après l'introduction et avant l'instruction elle-même, comment passer à ce mode:



2) Si la capture d'écran fait référence à une étape spécifique des instructions, insérez-la après ou à l'intérieur de cette étape:



Si vous devez insérer une capture d'écran d'un bouton, d'une icône ou d'un autre élément d'interface, vous devez l'insérer après le nom de cet élément:



N'utilisez pas de graphiques pour illustrer des choses évidentes.

Plus précisément, n'utilisez pas de captures d'écran pour illustrer:

• Le menu
• Icônes, boutons et onglets qui ont un nom
• Tout le reste qui peut être facilement et facilement décrit par des mots.

Conseils supplémentaires pour ceux qui écrivent de la documentation en anglais:


1) Comment capitaliser les titres:

majuscules Trois styles de majuscules sont disponibles: le style de phrase, le style de titre et toutes les majuscules.

• Capitalisation de style phrase: cette ligne fournit un exemple de capitalisation de style phrase.
• Capitalisation de style titre: cette ligne fournit un exemple de capitalisation de style titre.
• Toutes les majuscules: CETTE LIGNE OFFRE UN EXEMPLE DE TOUTES LES CAPSULES.

N'utilisez pas de majuscules pour mettre l'accent.

majuscule (style de phrase): lorsque vous utilisez une majuscule de style phrase, mettez en majuscule la première lettre du premier mot, ainsi que la première lettre des noms et adjectifs appropriés.
majuscule (style de titre): utilisez la majuscule de style titre pour les titres de livre, les titres de partie, les titres de chapitre et les titres de section (têtes de texte).

Suivez ces règles lorsque vous utilisez des majuscules de style titre. Mettez en majuscule chaque mot sauf:

• Articles (a, an, the), sauf si un article est le premier mot ou suit un deux-points
• Coordination des conjonctions (et, mais, ou, ni, pour, encore, etc.)
• Le mot à l'infinitif (Comment connecter votre imprimante)
• Le mot comme, quelle que soit la partie du discours
• Mots qui commencent toujours par une lettre minuscule, comme iPhone et iPad.
• Prépositions de quatre lettres ou moins (at, by, for, from, in, into, of, off, on, on, out, over, to, up et with), sauf lorsque le mot fait partie d'une expression verbale. Par exemple:
  
  Démarrez ComputerLog
  Dans le ServerGet
  Démarré avec Parallels Desktop

Capitaliser:

• Le premier et le dernier mot, quelle que soit la partie du discours:
Pour les utilisateurs Linux

À quoi servent les outils Parallels

• Le deuxième mot d'un composé avec trait d'union:

Correct: événements de haut niveau, adressage 32 bits
Incorrect: événements de haut niveau, adressage 32 bits
Exceptions: Intégré, Plug-in

• Les mots Are, If, Is, It, Than, That et This

2) Comment utiliser le mot «clic»:

cliquez sur Cliquez pour décrire l'action de positionner le pointeur sur un objet à l'écran et d'appuyer brièvement sur le bouton de la souris et de le relâcher. N'utilisez pas cliquez sur. Comme la plupart des utilisateurs savent ce qu'est un clic, vous devez le définir uniquement dans la documentation conçue pour les utilisateurs débutants, comme les didacticiels.
Correct: cliquez sur Mac si vous souhaitez utiliser le périphérique USB avec Mac OS X.

Incorrect: pointez sur Mac et cliquez dessus si vous souhaitez utiliser le périphérique USB sous Mac OS X.
cliquez sur Ne pas utiliser; utilisez le clic.

3) Courriel ou e-mail?

Utilisez l'email. N'utilisez pas de courrier électronique.

4) Si ou si?

Utilisez if pour exprimer une condition. Utilisez s'il faut exprimer des alternatives.
Correct: Vérifiez si Parallels Tools a été installé.
Incorrect: Vérifiez si les Outils Parallels ont été installés.
Correct: cliquez sur Mac si vous souhaitez utiliser le périphérique USB avec Mac OS X.

5) Comment utiliser les noms de produits:

Suivez le style de capitalisation sur l'emballage du produit. Utilisez le nom complet du produit pour sa première occurrence dans une section de texte (par exemple, un chapitre). Par la suite, le cas échéant, utilisez une version abrégée du nom du produit.

Par exemple: Parallels Desktop 14 pour Mac: Lors de la première occurrence dans une section de texte, utilisez Parallels Desktop 14 pour Mac.

Lors des occurrences suivantes, utilisez Parallels Desktop.

Conclusion

Dans ces 3 parties du manuel, nous avons essayé de rassembler, résumer et structurer les conseils qui vous aideront à rendre votre documentation plus facile et plus compréhensible.

Nous n'insistons pas sur le fait que l'écriture est nécessaire de cette façon - il existe de nombreuses approches de la documentation et des techniques. Regardez le réglage et utilisez ceux qui vous conviennent.

Merci beaucoup pour votre attention et votre intérêt!