Mauvais conseil: comment rédiger la documentation technique? Deuxième partie

Conseils pour rédiger avec compétence la documentation technique pour les utilisateurs.
2e partie

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

Vous pouvez lire le début de l'article ici , mais nous avons décrit le processus de documentation et de localisation de nos produits plus haut dans cet article .

Dans cette partie, nous analyserons en détail les sujets qui comprennent principalement la documentation utilisateur (en particulier le Guide de l'utilisateur) - à savoir, les sujets de tâches , qui décrivent comment résoudre un problème spécifique.



Combien de tâches décrire dans le sujet - une ou plusieurs?

Une rubrique de tâche peut décrire à la fois une tâche - «Lancer une application Windows» («Lancer une application Windows»), ainsi que plusieurs tâches connexes. Par exemple, la rubrique «Optimiser les performances» peut comprendre les sections suivantes: «Conserver automatiquement l'espace disque» et «Régler votre MacBook pour de meilleures performances ou économiser la batterie» («Optimiser votre MacBook pour une durée de vie de la batterie plus longue ou des performances supérieures »).

Nous devons essayer d'écrire des sujets de tâche sur le principe: un sujet - une tâche. Certes, il existe une exception - si vous avez deux tâches opposées en action, elles doivent être décrites dans une seule rubrique. Par exemple, si vous devez décrire comment basculer la machine virtuelle en mode plein écran et comment la quitter plus tard, vous devez le faire dans la même rubrique.
Si vous devez décrire plusieurs tâches connexes, cela peut également être fait dans une seule rubrique, à condition que leur description ne soit pas longue.

Sections de sujets de tâches

Les sujets de tâches comprennent:

• Titre
• Partie introductive (en anglais «intro»)
• Phrases, ce qui conduit à une description de ce que l'utilisateur doit faire exactement (en anglais «étape titre»)
• Numérotées ou en commençant par un grand nombre d'étapes (en anglais «étapes numérotées ou à puces»)
• La dernière partie (en anglais «outro»)

Il arrive parfois que la rubrique de tâche ne contienne pas toutes les sections ci-dessus - par exemple, il n'est pas nécessaire d'insérer Intro ou Outro. De plus, nous nous attarderons plus en détail sur chaque section du sujet.

Titre

Nous devons essayer de créer de tels titres afin que l'utilisateur comprenne immédiatement ce qui sera écrit dans le sujet.

Faites les gros titres, mais pas trop longtemps en même temps. Les en-têtes longs peuvent ne pas être entièrement affichés dans certains navigateurs ou dans la visionneuse d'aide Apple.

Lors de l'écriture d'un titre, utilisez l'impératif ("Do this")

Par exemple, «Configurer une imprimante à l'aide de Bonjour».

N'utilisez pas l'impératif dans les noms des sujets qui ne décrivent pas comment résoudre un problème.

Utilisez des mots conviviaux dans le nom du sujet, ne vous concentrez pas sur les éléments d'interface.

L'utilisateur ne veut pas comprendre les fonctionnalités, les termes, les éléments d'interface, etc. - il doit résoudre son problème spécifique. Par conséquent, au nom du sujet, essayez d'utiliser les mots que l'utilisateur lui-même utiliserait. Par exemple, si vous appelez la rubrique «Configurer votre Mac pour utiliser des applications Windows», cela sera beaucoup plus compréhensible pour l'utilisateur que la rubrique «À propos des machines virtuelles».

Essayez de formuler l'objectif comme l'utilisateur le ferait probablement. Par exemple, au lieu de «Démarrer une session à distance» - mieux nommer la rubrique «Démarrer le contrôle de Windows à distance».

Si vous devez utiliser des termes ou des noms d'interface techniquement complexes, il vaut mieux ne pas le faire dans l'en-tête, mais dans l'introduction de la rubrique.

Si vous écrivez de la documentation en anglais, les mots du titre doivent commencer par une majuscule

Droite : configurez votre Mac pour utiliser les applications Windows

Mauvais : configurez votre Mac pour utiliser les applications Windows

(Nous discuterons de la capitalisation de la rubrique plus en détail dans la prochaine partie du manuel).

Intro (Intro)

Dans la partie introductive, qui va immédiatement après l'en-tête, vous devez écrire ce que l'utilisateur doit savoir avant de commencer à effectuer la tâche.

Le prologue peut contenir:

• Informations générales supplémentaires: ce que l'utilisateur peut faire.
• Motivation : pourquoi l'utilisateur peut avoir besoin d'effectuer l'une ou l'autre action. Voici un exemple d'introduction qui explique pourquoi vous devrez peut-être télécharger et utiliser des machines virtuelles prêtes à l'emploi:

Utilisez des machines virtuelles prêtes à l'emploi

Si vous n'avez pas le temps de créer une nouvelle machine virtuelle avec la configuration nécessaire, vous pouvez télécharger la machine virtuelle terminée avec une configuration préconfigurée.

• Avertissements concernant tout dommage possible au matériel, aux logiciels ou à la perte de données pouvant survenir pendant que l'utilisateur effectue une action.
• Informations importantes sur les problèmes ou difficultés potentiels qui, bien qu'ils n'entraînent pas de dommages à la santé, à l'équipement ou à la perte de données, peuvent survenir lors de l'exécution d'une tâche.
• Explication: que signifie tel ou tel terme ou comment fonctionne une fonctionnalité.

Par exemple, si un utilisateur Parallels Desktop veut travailler avec macOS et Windows en même temps, comme s'il s'agissait d'un seul système d'exploitation, alors dans la partie introductive, vous pouvez parler de «Mode de cohérence» afin de préparer l'utilisateur à des termes qui sera davantage utilisé dans le sujet.

• Informations sur les conditions supplémentaires : par exemple, dans la rubrique qui décrit comment connecter l'imprimante via Bonjour, l'intro peut vous indiquer quelles versions de Windows prennent en charge Bonjour.
• Conditions nécessaires à la tâche en cours : si avant de commencer à effectuer les tâches décrites dans la rubrique, l'utilisateur doit faire ou vérifier autre chose, cela doit être mentionné dans la partie introductive. Et ce serait bien de donner des liens vers des sujets où il est décrit afin que l'utilisateur puisse rapidement trouver et lire.

N'insérez pas le prologue là où il n'est pas nécessaire.

Bien que la partie introductive fournisse des informations supplémentaires utiles, parfois tout est clair à partir du titre lui-même. Dans de tels cas, vous n'avez pas besoin de proposer un texte d'introduction, si seulement il l'était.

Par exemple:

Lancez des applications Mac via le menu Démarrer

Ouvrez le menu Démarrer de Windows et effectuez l'une des opérations suivantes:

• Cliquez sur Tous les programmes> Applications partagées Parallels et sélectionnez l'application souhaitée.
• Saisissez le nom de l'application dans le champ de recherche et sélectionnez l'application souhaitée parmi les options proposées.

Ne faites pas le prologue trop long

L'introduction ennuie trop longtemps l'utilisateur. Dans de tels cas, les utilisateurs l'ignorent souvent et accèdent directement à la liste des étapes spécifiques.

Si la partie introductive est trop grande, vous devez mentionner la principale et donner un lien vers une page conceptuelle ou une page de référence distincte, dans laquelle tout sera déjà décrit en détail.

Parfois, pour faciliter visuellement la lecture d'un texte long dans la partie introductive, des puces peuvent être utilisées. Par exemple:



Ne dites pas dans l'introduction comment terminer la tâche

Le prologue n'est pas pour ça. Ce qui doit être fait, où et comment - il est nécessaire de décrire seulement plus tard, après la partie introductive.

Cependant, dans de rares cas, vous devrez peut-être indiquer aux utilisateurs ce dont ils ont besoin pour effectuer la tâche. Dans l'exemple ci-dessous, la partie introductive indique aux utilisateurs ce dont ils ont besoin pour effectuer la tâche décrite dans la rubrique.



Ne décrivez pas les résultats de la tâche dans la partie introductive

Cela devrait être fait dans la dernière partie ( Outro ).

La phrase avant les instructions (en-tête d'étape)

Après Intro, vous devez insérer une phrase «introductive» (en anglais - «étape titre»), qui conduit l'utilisateur à des instructions: ce qui doit être fait exactement pour obtenir l'un ou l'autre résultat.

Par exemple, dans Intro, nous écrivons: « Si vous avez un disque d'installation et une clé d'activation, vous pouvez les utiliser pour installer Windows sur une machine virtuelle. "

Après l'introduction, le titre de l'étape: « Pour installer Windows: »

Et puis les étapes elles-mêmes:

1) Cliquez ici.
2) Choisissez ceci.
3) Et ainsi de suite ...

Remarque: s'il n'y a pas d'introduction dans le sujet, l'en-tête de l'étape est facultatif.

Si le sujet décrit des étapes séquentielles, l'en-tête de l'étape doit ressembler à « Pour faire quelque chose:» («Pour faire X:»).
Par exemple: «Pour passer en mode plein écran:» («Pour démarrer Windows:») ou « Pour passer en mode plein écran:» .

N'oubliez pas de mettre un deux-points à la fin

Si l'en-tête utilise des mots conviviaux et que vous devez utiliser des termes techniques complexes ou les noms des éléments d'interface dans les instructions, vous pouvez effectuer les opérations suivantes: dans la partie introductive, vous expliquez ce que signifie le terme, et dans l'en-tête de l'étape, vous l'utilisez déjà activement.

Par exemple:

1) nous rendons l'en-tête plus clair pour l'utilisateur:

" Configurer Windows pour occuper tout l'écran"

2) Ensuite, dans l'introduction, nous introduisons le terme «mode plein écran».

3) Après cela, dans le titre de l'étape, vous pouvez déjà utiliser le terme sans craindre qu'il ne soit pas compréhensible pour l'utilisateur:

" Pour entrer en plein écran:" ("Pour entrer en plein écran:")

Si les étapes décrites dans la rubrique ne sont pas une séquence d'actions, mais plusieurs façons d'atteindre l'objectif, le titre de l'étape doit être effectué comme suit: «Voici quelques façons de faire quelque chose:» («Voici des façons de faire X:») ou « Pour ce faire, effectuez l'une des opérations suivantes: » (« Pour effectuer X, effectuez l'une des opérations suivantes: »).

Par exemple, «Voici comment arrêter Windows:») ou « Pour connecter une imprimante, effectuez l'une des opérations suivantes: » («Pour connecter une imprimante, effectuez l'une des opérations suivantes: ”).

Lors de la création d'un en-tête d'étape, vous devez utiliser ces mots qui reflètent la tâche décrite dans la rubrique de tâche. Voici quelques exemples en anglais:

Titre de la page : installer Windows à partir d'un disque d'installation.
Couvertures des tâches : installation de Windows à l'aide d'un disque d'installation.
En - tête de l'étape : pour installer Windows.

Titre de la page : Ajuster les paramètres de cohérence.
Couvertures des tâches : personnalisation de l'apparence et du comportement de Windows en mode Cohérence.
En-tête d'étape: pour personnaliser le mode de cohérence.

Titre de la page : configurer Windows pour occuper tout l'écran
Couvertures de tâches : entrée en mode plein écran.
En - tête de l'étape : pour passer en mode plein écran, effectuez l'une des opérations suivantes:

Étapes numérotées

Tous les sujets qui décrivent comment effectuer une tâche particulière contiennent des instructions sur ce qu'il faut faire. Ces actions dans le texte sont généralement soit numérotées (s'il s'agit d'une série d'étapes consécutives) soit mises en évidence par des puces (s'il est proposé de choisir l'une des listes à votre discrétion).

Gardez la liste des étapes nécessaires aussi courte que possible.

Choisissez et décrivez le moyen le plus simple et le plus rapide de terminer une action. Des méthodes alternatives peuvent être décrites dans la dernière partie (Outro) ou dans une autre rubrique de tâche. Ne forcez pas l'utilisateur à lire les instructions en 4 étapes, si tout de même peut être fait en cliquant sur un bouton.

Si le moyen le plus simple consiste à exécuter l'action via la barre d'outils, décrivez cette option. Si la barre d'outils peut être personnalisée à votre convenance et que vous avez des doutes, la configuration utilisateur de la barre d'outils diffère soudainement de celle décrite dans la rubrique, décrivez tout comme cela se fait avec les paramètres par défaut. Comme le montre la pratique, la plupart des utilisateurs ordinaires modifient rarement les paramètres "d'usine".

Si vous devez décrire plusieurs façons d'exécuter une action dans un sujet :

Si, dans de nombreux sujets de tâches de votre livre, une certaine action est répétée et peut être effectuée de différentes manières (par exemple, via un menu ou une barre d'outils), sélectionnez une méthode et mentionnez-la de manière séquentielle dans chaque sujet de tâche.

S'il existe une alternative simple et courte, et que vous voulez certainement en parler, vous pouvez le faire en même temps.

Par exemple: «Pour ouvrir la configuration de la machine virtuelle, choisissez Actions> Configurer ou cliquez sur l'icône Configurer dans le coin supérieur droit.»).

Numérotez les étapes à effectuer séquentiellement.

Afin de ne pas gonfler la description et de ne pas mettre en évidence des instructions très courtes dans des étapes distinctes (telles que «Cliquez sur OK»), vous pouvez combiner 2 actions liées et connexes en une seule étape, comme indiqué ci-dessous:



Utilisez des puces pour mettre en évidence des actions incohérentes

Parfois, l'utilisateur dispose de plusieurs façons de choisir comment atteindre l'objectif. Dans de tels cas, les options proposées émettent des balles.

Par exemple:


Si la liste contient les noms des éléments graphiques, mettez-les en surbrillance pour plus de clarté en gras

Si l'action à effectuer par l'utilisateur répertorie un certain nombre d'éléments de l'interface graphique (éléments de menu, daws, etc.), démarrez chaque option à partir d'une nouvelle ligne, en surlignant le nom de l'élément en gras. Après l'élément marqué en gras, mettez deux points puis expliquez la description en texte clair.

Comme le montre cet exemple:


Si le texte de la rubrique fait souvent référence à divers éléments d'interface, il peut être utile de créer une rubrique d'aide distincte dans laquelle ces éléments seront décrits.

Cela sera particulièrement utile si de nombreux sujets du guide font référence aux mêmes éléments. Dans ce cas, au début du sujet, vous devez donner un lien vers le sujet de référence dans lequel l'élément mentionné est expliqué.

Si cet élément est à nouveau mentionné plus loin dans le texte, vous n'avez plus besoin de lui donner un lien - un seul au début. Lorsqu'il y a beaucoup de liens dans le sujet, cela peut compliquer la perception et la compréhension de l'écrit.

La dernière partie (Outro)

Outro est l'information finale qui vient après les étapes numérotées. Essayez de raccourcir la dernière partie - n'utilisez pas plus de 3 paragraphes, chacun composé d'un maximum de 3 phrases.

Utilisez Outro pour décrire les résultats ou les conséquences de ces actions.

Un exemple de résultat ou de conséquences peut être:

• Informations sur l'emplacement d'installation des fichiers;

• Un message apparaît qui nécessitera des actions supplémentaires de la part de l'utilisateur;

• Paramètres que l'utilisateur devra changer une fois les actions décrites terminées.

Par exemple, la dernière partie de la rubrique sur la façon de faire fonctionner Parallels Access uniquement sur Wi-Fi, dit ce qui suit: « Si vous avez configuré Parallels Access pour fonctionner uniquement sur Wi-Fi et qu'aucun réseau sans fil n'est actuellement détecté, un message apparaît vous demandant - Souhaitez-vous vous connecter via 3G? ".

Dans la dernière partie du sujet, vous pouvez décrire une autre manière de terminer la tâche.

Si la méthode alternative peut être décrite en une phrase, vous pouvez le faire dans la dernière partie du sujet.

Outro peut fournir plus d'informations relatives à la tâche en cours.

Ces informations peuvent informer les utilisateurs de ce qu'ils peuvent faire d'autre une fois la tâche décrite terminée.

Dans l'exemple suivant, la rubrique décrit comment rechercher un fichier à partir d'une machine virtuelle dans le Finder macOS. Et dans la dernière partie de la rubrique, décrit ce que l'utilisateur peut faire d'autre avec le fichier une fois le fichier trouvé.



Dans Outro, vous pouvez décrire des informations supplémentaires dont seuls certains utilisateurs ont besoin.

Par exemple, dans la dernière partie de la rubrique sur l'intégration de machines virtuelles Windows dans macOS, vous pouvez écrire ce qui suit: «Si vous avez un MacBook Pro 2016 ou version ultérieure, vous pouvez travailler avec certaines applications Windows à l'aide de la Touch Bar»


Divisez les tâches longues en étapes courtes

Fondamentalement, les sujets de tâche sont courts et tiennent sur une seule page. Cependant, si une tâche complexe et très longue est décrite, qui peut être divisée en étapes, étapes et procédures, il convient de séparer logiquement les informations et de décrire chaque étape dans une rubrique distincte afin que la description soit plus simple, mieux lue et comprise.

Ce qui suit est un exemple tiré du contenu du Guide de l'utilisateur de Parallels Desktop. La capture d'écran montre un chapitre qui décrit les différentes façons d'installer Windows sur une machine virtuelle. Et l'une des façons - comment importer des données à partir d'un ordinateur distant - est divisée en plusieurs rubriques.



À suivre ...

(dans la partie suivante, nous parlerons davantage des sujets conceptuels et de référence et des sujets qui aident à résoudre les problèmes)