La documentation logicielle n'est qu'un ensemble d'articles. Mais même ceux-ci peuvent être frustrants. D'abord, il faut longtemps chercher le bon guide. Ensuite, on s'attaque à un texte peu clair. On suit les instructions, mais le problème persiste. On cherche un autre article, on s'énerve... Au bout d'une heure, on abandonne tout. Voilà comment fonctionne une mauvaise documentation. Qu'est-ce qui la rend ainsi et comment y remédier ? Lisez la suite.
Notre ancienne documentation avait de nombreux défauts. Cela fait presque un an que nous travaillons à sa refonte pour que le scénario décrit ci-dessus ne concerne pas nos clients. Regardez, et .
Problème 1. Articles confus et mal rédigés
Si la documentation est incompréhensible, quel en est l'intérêt ? Mais personne n'écrit des articles confus intentionnellement. Ils résultent d'un auteur qui ne pense pas à son public ni à son objectif, qui noie le poisson et ne vérifie pas son texte pour détecter les erreurs.
- Public. Avant d'écrire un article, il est essentiel de réfléchir au niveau de préparation du lecteur. Il est logique que dans un article pour débutants, il ne faille pas omettre les étapes de base et laisser les termes techniques sans explication, tandis que dans un article sur une fonctionnalité rare utile uniquement aux professionnels, il est inapproprié d'expliquer le terme PHP.
- L'objectif. Une autre chose à laquelle il est préférable de réfléchir à l'avance. L'auteur doit avoir un objectif clair, définir l'action utile de l'article, et décider ce que le lecteur va faire après l'avoir lu. Si cela n'est pas fait, on finit par avoir une description pour le plaisir de décrire.
- Eau et erreurs. Trop d'informations superflues et de langages bureaucratiques, des erreurs et des fautes d'orthographe nuisent à la perception. Même si le lecteur n'est pas un nazi de la grammaire, le manque de soin dans le texte peut le rebuter.
Gardez à l'esprit les conseils ci-dessus, et les articles deviendront plus clairs — c'est garanti. Pour faire encore mieux, adoptez nos .
Problème 2. Les articles ne répondent pas à toutes les questions
C'est problématique lorsque la documentation ne suit pas le rythme du développement, ne répond pas aux questions réelles et que les erreurs restent sans correction pendant des années. Ce n'est pas tant un problème de l'auteur que de l'organisation des processus au sein de l'entreprise.
La documentation ne suit pas le développement
La fonctionnalité est déjà sortie, le marketing prévoit de la promouvoir, et il s'avère qu'il n'y a toujours pas de nouvel article ou de traduction dans la documentation. À cause de cela, nous avons même dû reporter la sortie. Peu importe combien de fois nous demandons à tous de transmettre la tâche aux rédacteurs techniques à temps, cela ne fonctionnera pas. Si nous n'automatisons pas le processus, la situation se reproduira.
Nous avons apporté des changements à YouTrack. La tâche d'écrire un article sur la nouvelle fonctionnalité est attribuée au rédacteur technique dès que la possibilité commence à être testée. C'est à ce moment-là que le marketing en prend connaissance pour se préparer à la promotion. Des notifications arrivent également dans le messager d'entreprise Mattermost, il est donc impossible de manquer les nouvelles des développeurs.
La documentation ne reflète pas les demandes des utilisateurs
Nous avons l'habitude de travailler de cette manière : la fonctionnalité est lancée, nous en faisons part. Nous décrivons comment l'activer, la désactiver, et effectuer des réglages fins. Mais que faire si le client utilise notre logiciel d'une manière que nous n'avions pas prévue ? Ou s'il rencontre des erreurs auxquelles nous n'avons pas pensé ?
Pour que la documentation soit aussi complète que possible, nous conseillons d'analyser les requêtes au support, les questions sur les forums spécialisés, et les recherches sur les moteurs de recherche. Les sujets les plus populaires doivent être transmis aux rédacteurs techniques afin qu'ils complètent les articles existants ou en écrivent de nouveaux.
La documentation ne s'améliore pas
Il est difficile de faire tout parfaitement dès le départ, des erreurs apparaîtront inévitablement. On peut espérer des retours d'information des clients, mais il est peu probable qu'ils signalent chaque faute de frappe, inexactitude, article peu clair ou introuvable. En plus des clients, les employés lisent également la documentation et voient donc les mêmes erreurs. Nous pouvons tirer parti de cela ! Il suffit de créer des conditions qui facilitent le signalement des problèmes.
Nous avons un groupe sur le portail interne où les employés laissent des remarques, suggestions et idées concernant la documentation. Le support a besoin d'un article, mais il n'est pas là ? Un testeur a remarqué une inexactitude ? Un partenaire s'est plaint aux managers du développement d'erreurs ? Tout va dans ce groupe ! Les rédacteurs techniques corrigent certaines choses immédiatement, d'autres sont transférées dans YouTrack, et certaines sont prises en considération. Pour que le sujet ne s'essouffle pas, nous rappelons régulièrement l'existence du groupe et l'importance des retours.
Problème 3. L'article nécessaire est difficile à trouver
Un article qui ne peut pas être trouvé n'est pas mieux qu'un article qui n'existe pas. La devise d'une bonne documentation devrait être « Facile à chercher, facile à trouver ». Comment y parvenir ?
Organiser la structure et définir le principe de choix des sujets. La structure doit être aussi transparente que possible pour que le lecteur ne se demande pas « Où puis-je trouver cet article ? ». En résumé, il existe deux approches : par l'interface et par les tâches.
- Par l'interface. Le contenu duplique les sections du panneau. C'était le cas dans l'ancienne documentation d'ISPsystem.
- Par les tâches. Les titres des articles et des sections reflètent les tâches des utilisateurs ; dans les titres, il y a presque toujours des verbes et des réponses à la question « comment faire ». Nous adoptons maintenant ce format.
Quelle que soit l'approche que vous choisissez, assurez-vous que le sujet correspond aux demandes des utilisateurs et est traité de manière à ce que l'utilisateur puisse résoudre son problème.
Mettre en place une recherche centralisée. Dans un monde idéal, la recherche devrait fonctionner, même lorsque vous faites des erreurs typographiques ou que vous commettez des erreurs de langue. Notre recherche dans Confluence ne peut pas encore offrir cela. Si vous avez plusieurs produits et que la documentation est générale, adaptez la recherche à la page où se trouve l'utilisateur. Dans notre cas, la recherche sur la page d'accueil fonctionne pour tous les produits, et si vous êtes déjà dans une section spécifique, elle ne fonctionne que pour les articles de cette section.
Ajouter un contenu et des « fils d'Ariane ». Il est préférable que chaque page dispose d'un menu et de fils d'Ariane — le chemin de l'utilisateur vers la page actuelle avec la possibilité de revenir à n'importe quel niveau. Dans l'ancienne documentation d'ISPsystem, il fallait sortir de l'article pour accéder au contenu. C'était peu pratique, donc nous avons corrigé cela dans la nouvelle documentation.
Ajouter des liens dans le produit. Si les gens contactent le support avec la même question encore et encore, il est judicieux d'ajouter un conseil avec sa solution dans l'interface. Si vous avez des données ou une compréhension du moment où l'utilisateur rencontre un problème, vous pouvez également l'informer par e-mail. Montrez de l'attention et réduisez la charge du support.
À droite, dans la fenêtre contextuelle, se trouve le lien vers l'article sur la configuration de DNSSEC dans la section de gestion des domaines d'ISPmanager
Configurer des liens croisés dans la documentation. Les articles qui sont liés entre eux doivent être « liés ». Si les articles forment une séquence, n'oubliez pas d'ajouter à la fin de chaque texte des flèches vers l'avant et vers l'arrière.
Très probablement, une personne cherchera d'abord la réponse à sa question non chez vous, mais dans un moteur de recherche. C'est frustrant s'il n'y a pas de liens vers la documentation pour des raisons techniques. Donc, prenez soin de l'optimisation pour les moteurs de recherche.
Problème 4. Un formatage obsolète nuit à la perception
Outre les mauvais textes, le design peut également gâcher la documentation. Les gens sont habitués à lire des matériaux bien formatés. Les blogs, les réseaux sociaux, les médias — tout le contenu est présenté de manière non seulement esthétique, mais aussi agréable à lire, plaisant pour les yeux. Il est donc facile de comprendre la souffrance d'une personne qui voit un texte comme sur la capture d'écran ci-dessous.
Dans cet article, il y a tellement de captures d'écran et de mises en évidence qu'elles nuisent à la perception (l'image est cliquable)
Il ne faut pas transformer la documentation en un long récit avec plein d'effets, mais il est important de prendre en compte les règles de base.
Mise en page. Déterminez la largeur du texte principal, la police, la taille, les titres et les marges. Impliquez un designer, et pour accepter le travail ou vous débrouiller vous-même, lisez le livre d'Artem Gorbunov «Typographie et mise en page». Cela présente une seule perspective sur la mise en page, mais elle suffira amplement.
Mises en évidence. Déterminez ce qui nécessite des accents dans le texte. Cela inclut généralement le chemin dans l'interface, les boutons, les extraits de code, les fichiers de configuration, les blocs «Attention». Précisez comment seront les mises en évidence de ces éléments et fixez-le dans le règlement. Gardez à l'esprit que moins il y a de mises en évidence, mieux c'est. Quand il y en a trop, le texte devient «bruyant». Même les guillemets créent du bruit s'ils sont utilisés trop souvent.
Captures d'écran. Accordez-vous avec l'équipe sur les cas dans lesquels des captures d'écran sont nécessaires. Il n'est pas nécessaire d'illustrer chaque étape. Un grand nombre de captures d'écran, y compris des petits boutons, nuisent à la perception et gâchent la mise en page. Déterminez la taille, ainsi que le format des mises en évidence et des légendes sur les captures d'écran, fixez cela dans le règlement. Rappelez-vous que les illustrations doivent toujours correspondre à ce qui est écrit et être à jour. Encore une fois, si le produit est régulièrement mis à jour, il sera difficile de suivre chaque changement.
Longueur du texte. Évitez les articles trop longs. Divisez-les en sections, et si cela n'est pas possible, ajoutez un sommaire avec des liens d'ancrage au début de l'article. Une manière simple de rendre un article visuellement plus court est de cacher les détails techniques, nécessaires à un public restreint, sous un spoiler.
Formats. Combinez plusieurs formats dans vos articles : texte, vidéo et images. Cela améliorera la compréhension.
Ne tentez pas de masquer les problèmes avec une belle mise en page. Honnêtement, nous espérions que l'"emballage" sauverait notre documentation obsolète — ce ne fut pas le cas. Les textes contenaient tellement de bruit visuel et de détails superflus que les réglementations et le nouveau format étaient impuissants.
Beaucoup de ce qui précède sera déterminé par la plateforme que vous utilisez pour votre documentation. Pour nous, par exemple, c'est Confluence. Nous avons également dû y travailler. Si cela vous intéresse, lisez le témoignage de notre développeur web : .
Par où commencer les améliorations et comment survivre
Si votre documentation est aussi vaste que celle d'ISPsystem et que vous ne savez pas par où commencer, concentrez-vous sur les problèmes les plus sérieux. Les clients ne comprennent pas la documentation — travaillez à améliorer les textes, créez des règlements, formez les auteurs. Si la documentation est obsolète — occupez-vous des processus internes. Commencez par les articles les plus populaires concernant les produits les plus demandés : demandez au support, consultez les analyses du site et les requêtes sur les moteurs de recherche.
Disons-le tout de suite — ce ne sera pas facile. Et cela ne se fera probablement pas rapidement non plus. À moins que vous ne commenciez tout juste et que vous fassiez tout correctement dès le départ. Une chose est certaine — cela s'améliorera avec le temps. Mais le processus ne se terminera jamais :-).
Source : habr.com
