Conseils pour rédiger avec compétence la documentation technique pour les utilisateurs.
Partie 1
Dans un article précédent, nous avons expliqué comment se déroule le processus de
documentation et de localisation de nos produits .
Cette fois, sous la coupe, se trouve le manuel de
notre rédacteur technique Andrei Starovoitov, qui vous aidera à rendre votre documentation plus facile et plus compréhensible pour les utilisateurs (les techniques décrites sont utilisées par Apple, Microsoft et d'autres sociétés pour documenter leurs produits).
Comme vous le savez, une bonne documentation n'est pas un luxe, mais un moyen d'augmenter les ventes de l'entreprise. Si vous allez démarrer ou développez déjà une sorte de programme, alors pour entrer sur le marché mondial avec lui, vous aurez besoin d'un manuel d'utilisation (aka Guide de l'utilisateur) ou au moins d'un document qui explique aux clients comment commencer à travailler avec votre produit (le soi-disant Mise en route avec).
Dans quelle langue rédiger la documentation - en russe, puis la traduire, ou immédiatement en anglais - vous décidez. Chez Parallels, nous avons choisi la deuxième approche. Il est souvent beaucoup plus facile de faire une description en anglais, car presque tous (et maintenant nous pouvons dire que "tous") les termes informatiques en russe sont empruntés.
Plus loin dans le texte, nous nous concentrerons sur les exemples russes et anglais.
Alors, que devez-vous rechercher lors de la rédaction de la documentation?
Types de sujets dans la documentation
Lors de la rédaction d'un sujet, vous devez d'abord déterminer de quel type de sujet il s'agit :)
Cela dépendra de quoi et comment l'écrire.
Il existe
4 principaux types de sujets :
•
Sujets décrivant comment résoudre un problème particulier ou plusieurs tâches connexes (en anglais, ce type de sujet est appelé
pages de tâches) .
Par exemple, «Installer Parallels Desktop» ou «Arrêter ou suspendre Windows». Chacune de ces rubriques décrit une série d'une ou plusieurs étapes qu'un utilisateur doit suivre pour atteindre un objectif spécifique. Le manuel d'utilisation se compose principalement de ces sujets.
Habituellement, les utilisateurs n'aiment pas lire, surtout quand il y a beaucoup de texte. Par conséquent, vous devez essayer de rendre ces sujets aussi courts que possible. Idéalement, si les informations sont présentées sous la forme suivante: «vous pouvez faire quelque chose, cliquez simplement ici et ici» (les sujets des tâches seront discutés plus en détail dans la prochaine partie de l'article).
Si le développeur estime qu'il existe des informations supplémentaires que l'utilisateur doit connaître, et qu'il y en a beaucoup, alors cela est mieux décrit dans les rubriques conceptuelles (voir ci-dessous).
•
Thèmes conceptuels (en anglais -
pages conceptuelles ). Dans ces rubriques, il n'y a pas d'instructions sur la façon de résoudre un problème. Ils contiennent des informations qui contribuent plutôt à une meilleure compréhension des choses. Par exemple, les sujets conceptuels sont utilisés pour:
- Expliquer aux utilisateurs exactement comment fonctionne un processus;
- dire ce qui peut être fait dans les paramètres de l'application;
- décrire les fonctionnalités ajoutées dans la nouvelle version du produit;
- fournir des informations supplémentaires qui aideront l'utilisateur à mieux comprendre ou résoudre un problème.
Veuillez noter que des informations supplémentaires (dans le cas où elles sont nombreuses) doivent être fournies précisément dans le sujet conceptuel afin de ne pas surcharger le sujet de la tâche.
•
Rubriques d'aide (en anglais -
pages de référence ) - contiennent des informations auxquelles l'utilisateur peut se référer périodiquement pour savoir ce que signifie un terme particulier, comment fonctionne une fonction, etc. Un bon exemple de ces sujets est le dictionnaire à la fin du guide (aka Glossaire). Les rubriques de référence sont particulièrement utiles pour expliquer l'objectif de divers éléments d'interface.
•
Sujets décrivant comment résoudre un problème (en anglais -
pages de dépannage ).
Par exemple: «Je ne peux pas activer Parallels Desktop» ou «Je ne peux pas me connecter à Internet». Ces rubriques décrivent ce qui doit être fait pour résoudre un problème. Ils peuvent également contenir des informations qui aideront à comprendre quelle est la cause du dysfonctionnement.
Instructions de base pour tous les types de documentation
Lors de la création d'un guide:
1)
Concentrez-vous sur l'utilisateur
• Au lieu de structurer la description du produit en fonction de ses fonctionnalités ou éléments d'interface, essayez de vous concentrer sur les tâches que l'utilisateur est le plus susceptible d'essayer de résoudre.
Par exemple, une rubrique sur la façon de protéger les données dans une machine virtuelle peut être appelée de deux manières:
a) «Paramètres de sécurité», qui décrit en détail ce qui peut être fait pour protéger les données.
b) Faites plusieurs sujets décrivant des tâches spécifiques:
- «Protégez vos données avec un logiciel antivirus»
- «Sauvegarder votre machine virtuelle» («Sauvegarder votre machine virtuelle»)
Selon les tendances actuelles de la documentation, la deuxième approche est préférable, car dans ce cas, l'utilisateur n'a pas à deviner s'il doit ou non faire quelque chose, et il reçoit des instructions claires sur ce qui doit être fait exactement.
• Se concentrer sur les tâches de l'utilisateur et son niveau de connaissances techniques.
Par exemple, dans la documentation pour l'utilisateur moyen, au lieu d'écrire «Créer une machine virtuelle», vous devez écrire «Installer Windows ou tout autre système d'exploitation», comme le terme « machine virtuelle »est loin d'être connue de tous. Ou un autre exemple - une rubrique qui décrit comment créer des raccourcis clavier rapides, il est préférable d'appeler «Configurer les raccourcis clavier» plutôt que «Paramètres du clavier».
Bien que ce soit le point, pour la majorité des lecteurs de Habr, il serait plus clair de "Configurer les raccourcis", mais la question est déjà de savoir dans quelle mesure un tel terme est approprié dans la terminologie officielle à l'heure actuelle :)
• Si cela n'est pas clair, expliquez pourquoi l'utilisateur peut avoir besoin d'effectuer une tâche particulière.
Par exemple:
• Lors de la description, essayez d'utiliser les mots que l'utilisateur utilise quotidiennement dans son discours. Si un terme techniquement complexe peut être remplacé par des mots plus simples, essayez toujours d'utiliser des mots plus simples.
Par exemple, «transparent» au lieu de «transparent». Si vous donnez un exemple de la langue anglaise, utilisez "use" au lieu de "use".
2)
Essayez de donner toutes les informations nécessaires sans mots inutiles«Les ambassadeurs de l'île de Samos sont venus à Sparte pour demander de l'aide. Ils ont fait un long et beau discours. Les Spartiates ont déclaré: "Après avoir écouté la fin, nous avons oublié le début et en oubliant le début, nous n'avons pas compris la fin." Les Samosets étaient vifs d'esprit. Le lendemain, ils sont venus à la réunion avec un sac vide et n'ont dit que quatre mots: "Il y a un sac, il n'y a pas de farine". Les Spartiates les ont réprimandés - deux mots suffisaient: "il n'y a pas de farine", mais ils étaient satisfaits de ces esprits rapides et ont promis d'aider. "Si vous décrivez la fonctionnalité trop longtemps - personne ne la lira. Mais c'est aussi complètement «en spartiate», car si trop peu est écrit, il y aura des questions et des doutes, les utilisateurs commenceront à attirer l'équipe d'assistance. En général, il est important de maintenir l'équilibre.
Pour aider les utilisateurs à trouver toutes les informations dont ils ont besoin et en même temps décrire chaque section aussi brièvement que possible:
- Concentrez-vous sur les informations les plus importantes nécessaires pour résoudre le problème décrit dans la rubrique. Si certains détails ne sont pas nécessaires à la tâche, ne les décrivez pas.
- Pas besoin de documenter chaque clic. Si tout est clair dans l'interface, laissez l'utilisateur le découvrir lui-même. Par exemple, au lieu de documenter chaque étape de l'installation du programme, il est préférable d'écrire: «Pour installer le programme, suivez les instructions à l'écran.» Si, comme dernière étape d'une procédure, vous devez cliquer sur OK, cela ne vaut pas la peine d'être décrit.
- Au lieu de donner toutes les informations dans une rubrique, montrez à l'utilisateur où vous pouvez lire des informations supplémentaires en utilisant des liens vers d'autres rubriques, des liens vers des ressources externes ou insérez à la fin la section «Informations connexes», qui contiendra des liens vers des sujets liés à ce qui est décrit à l'écran.
- Si une tâche longue peut être divisée en plusieurs étapes ou sous-tâches, chacune étant une tâche distincte, divisez le sujet en sections appropriées ou créez une section dans le guide, composée de sujets décrivant chaque étape. Dans ce cas, n'oubliez pas d'insérer des liens vers des rubriques connexes.
- Si une tâche (par exemple, le démarrage d'une machine virtuelle) peut être effectuée de plusieurs manières, il n'est pas nécessaire de toutes les décrire. Il suffit de mentionner le moyen le plus rapide et le plus simple. Si vous pensez toujours qu'il est utile que l'utilisateur connaisse une autre méthode, décrivez-la à la fin (en anglais - Outro).
3)
Ne répétez pas les mêmes informations sur les pages
Au lieu de répéter des informations dans chaque rubrique qui sont déjà décrites dans une autre rubrique, il vaut mieux se référer qu’une description plus détaillée peut être trouvée dans une telle rubrique, ou simplement lui donner un hyperlien.
4)
Attirez correctement l'attention des utilisateurs
Lorsque la description doit attirer l'attention de l'utilisateur, les mots d'introduction suivants sont utilisés - «Attention!» (en anglais - Attention!), "Important:" (en anglais - Important :) et "Remarque:" (en anglais - Remarque :).
Chacun de ces mots implique son propre niveau «d'importance».
Afin de ne pas forcer l'utilisateur en vain, utilisez correctement chaque terme:
- Faites attention! (Attention! En anglais) pour indiquer une situation dangereuse qui, si elle n'est pas évitée, pourrait entraîner une perte de données, des dommages aux composants ou tout autre dommage.
- Utilisez "Important:" (en anglais - Important :) pour indiquer une situation importante et potentiellement problématique, qui, cependant, ne peut pas entraîner de dommages physiques, de dommages ou de perte de données.
- Utilisez «Remarque:» (Remarque :) pour fournir toute information supplémentaire relative à ce sujet. Bien qu'une telle insertion détache les utilisateurs de la tâche en cours, elle peut être utile.
Par exemple:
Pour ouvrir la configuration de la machine virtuelle, cliquez sur Actions> Configurer.
Remarque: La machine virtuelle doit être désactivée.
Utilisez la note «Remarque:» avec parcimonie - si vous l'insérez trop souvent, elle obstrue le texte et ne fait plus attention à elle.
Si possible, insérez «Attention!», «Important:» et «Remarque:» au début de la rubrique afin que l'utilisateur s'en rende compte avant de commencer à exécuter une procédure. Toutefois, si les informations se réfèrent uniquement à une étape particulière, insérez-les après cette étape.
Un exemple:
À suivre ...(dans la prochaine partie de l'article, nous aborderons plus en détail les sujets qui décrivent comment résoudre un problème spécifique)