La documentation du logiciel n'est qu'une collection d'articles, mais même ils peuvent vous rendre fou. Vous cherchez d'abord la bonne instruction pendant longtemps, puis vous comprenez le texte obscur, faites comme il est écrit, mais le problème n'est pas résolu. Vous cherchez un autre article, vous êtes nerveux ... Après une heure vous crachez sur tout et partez. Voici comment fonctionne une mauvaise documentation. Qu'est-ce qui le rend ainsi et comment y remédier - lire sous la coupe.
Notre ancienne documentation comportait de nombreux défauts. Depuis près d'un an, nous le traitons pour que le scénario décrit ci-dessus ne concerne pas nos clients. Voyez comment c'était et comment c'est devenu .
Problème 1. Articles incompréhensibles et mal écrits
S'il est impossible de comprendre la documentation, à quoi ça sert? Mais personne n'écrit d'objet obscur à dessein. Ils sont obtenus lorsque l'auteur ne pense pas au public et au but, verse de l'eau et ne vérifie pas le texte pour des erreurs.
- Le public . Avant d'écrire un article, vous devez réfléchir au niveau de préparation du lecteur. Il est logique que dans l'article pour débutant, vous ne sautiez pas les étapes de base et ne laissiez pas les termes techniques sans déchiffrement, et dans l'article par la fonctionnalité rare qui n'est nécessaire que pour les pros, mâchez le sens du mot PHP.
- But . Une autre chose à laquelle vous devriez penser à l'avance. L'auteur doit fixer un objectif clair, déterminer l'effet utile de l'article, décider de ce que le lecteur fera après l'avoir lu. Si cela n'est pas fait, une description est obtenue pour la description.
- L'eau et les insectes . Beaucoup d'informations inutiles et de cléricalisme, d'erreurs et de fautes de frappe interfèrent avec la perception. Même si le lecteur n'est pas une nation grammaticale, la négligence dans le texte peut le repousser.
Considérez les conseils ci-dessus, et les articles deviendront plus clairs - garantis. Pour le rendre encore meilleur, répondez à nos
50 questions lorsque vous travaillez sur la documentation technique .
Problème 2. Les articles ne répondent pas à toutes les questions
C'est mauvais quand la documentation ne suit pas le développement, ne répond pas aux vraies questions, les erreurs ne sont pas corrigées depuis des années. Ces problèmes ne sont pas tant l'auteur que l'organisation des processus au sein de l'entreprise.
La documentation ne suit pas le développement
La fonctionnalité est déjà dans la version, le marketing prévoit de la couvrir, et il s'avère que le nouvel article ou la traduction n'est toujours pas dans la documentation. Pour cette raison, nous avons même dû reporter la sortie. Vous pouvez demander à tout le monde de remettre la tâche aux rédacteurs techniques à temps, mais cela ne fonctionnera pas. Si le processus n'est pas automatisé, la situation sera répétée.
Nous avons apporté des modifications à YouTrack. La tâche d'écrire un article sur une nouvelle fonctionnalité incombe au rédacteur technique au moment même où il commence à tester l'opportunité. Ensuite, le marketing apprend à son sujet afin de se préparer à la promotion. Les notifications viennent également dans le messager d'entreprise Mattermost, il est donc tout simplement impossible de manquer les nouvelles des développeurs.
La documentation ne reflète pas les demandes des utilisateurs
On travaillait comme ça: une fonctionnalité est sortie, on en a parlé. Nous avons décrit comment l'activer, le désactiver, effectuer des réglages précis. Mais que faire si le client utilise notre logiciel d'une manière à laquelle nous ne nous attendions pas? Ou fait-il des erreurs auxquelles nous n'avons pas pensé?
Afin que la documentation soit la plus complète possible, nous vous conseillons d'analyser les demandes d'assistance, les questions sur les forums thématiques et les requêtes dans les moteurs de recherche. Les sujets les plus populaires devraient être transmis aux rédacteurs techniques pour compléter les articles existants ou en rédiger de nouveaux.
La documentation n'est pas améliorée
C'est difficile à faire tout de suite parfaitement, de toute façon il y aura des erreurs. Vous pouvez compter sur les commentaires des clients, mais il est peu probable qu'ils signalent chaque faute de frappe, inexactitude, article incompréhensible ou inconnu. En plus des clients, les employés lisent la documentation, ce qui signifie qu'ils voient les mêmes erreurs. Il peut être utilisé! Il suffit de créer des conditions dans lesquelles il sera facile de signaler un problème.
Nous avons un groupe sur le portail interne où les employés laissent des commentaires, des suggestions et des idées sur la documentation. Le support a besoin d'un article mais n'est-ce pas? Le testeur a-t-il remarqué une inexactitude? Le partenaire s'est plaint aux responsables du développement d'erreurs? Tout dans ce groupe! Les rédacteurs techniques réparent quelque chose tout de suite, transfèrent quelque chose sur YouTrack, réfléchissent à quelque chose. Pour garder le sujet calme, nous rappelons de temps en temps l'existence du groupe et l'importance du feedback.
Problème 3. Vous devez chercher le bon article pendant longtemps
Un article introuvable ne vaut pas mieux qu'un article qui ne l'est pas. La devise d'une bonne documentation devrait être «Facile à rechercher, facile à trouver». Comment y parvenir?
Rationalisez la structure et déterminez le principe du choix des sujets . La structure doit être aussi transparente que possible afin que le lecteur ne pense pas "Où puis-je trouver cet article?" Pour résumer, il existe deux approches: à partir de l'interface et à partir des tâches.
- Depuis l'interface. Le contenu duplique des sections du panneau. C'était donc dans l'ancienne documentation ISPsystem.
- De tâches. Les titres des articles et des sections reflètent les tâches des utilisateurs; les titres contiennent presque toujours des verbes et des réponses à la question «comment faire». Nous passons maintenant à ce format.
Quelle que soit l'approche que vous choisissez, assurez-vous que le sujet répond aux besoins des utilisateurs et est couvert afin que l'utilisateur résolve avec précision sa question.
Établissez une recherche centralisée . Dans un monde idéal, la recherche devrait fonctionner même lorsque vous êtes attristé ou confondu avec la langue. Notre recherche dans Confluence ne peut pas encore plaire. Si vous avez de nombreux produits et que la documentation est générale, adaptez la recherche à la page sur laquelle se trouve l'utilisateur. Dans notre cas, la recherche principale fonctionne sur tous les produits, et si vous êtes déjà dans une section spécifique, alors uniquement sur les articles qu'elle contient.
Ajoutez du contenu et du fil d'Ariane . C'est bien quand il y a un menu et du fil d'Ariane sur chaque page - le chemin de l'utilisateur vers la page actuelle avec la possibilité de revenir à n'importe quel niveau. Dans l'ancienne documentation ISPsystem, vous deviez quitter l'article pour accéder au contenu. C'était gênant, donc dans le nouveau nous l'avons corrigé.
Organisez les liens dans le produit . Si les gens viennent de temps à autre en support avec la même question, il est raisonnable d'ajouter un indice avec sa solution à l'interface. Si vous avez des données ou comprenez à quel moment l'utilisateur est confronté à un problème, vous pouvez également le lui signaler par newsletter. Faites attention et retirez la charge du support.
À droite dans la fenêtre pop-up se trouve un lien vers un article sur la configuration de DNSSEC dans la section de gestion de domaine ISPmanagerConfigurez des références croisées dans la documentation . Les articles liés doivent être «liés». Si les articles sont une séquence, assurez-vous d'ajouter des flèches avant et arrière à la fin de chaque texte.
Très probablement, une personne ira d'abord chercher une réponse à sa question, non pas à vous, mais à un moteur de recherche. C'est dommage s'il n'y a pas de liens vers la documentation pour des raisons techniques. Prenez donc soin de l'optimisation des moteurs de recherche.
Problème 4. La mise en page obsolète interfère avec la perception
En plus des mauvais textes, la conception peut ruiner la documentation. Les gens ont l'habitude de lire des documents bien faits. Blogs, réseaux sociaux, médias - tout le contenu est présenté non seulement beau, mais aussi facile à lire, agréable à l'œil. Par conséquent, vous pouvez facilement comprendre la douleur d'une personne qui voit le texte comme dans la capture d'écran ci-dessous.
Il y a tellement de captures d'écran et de sélections dans cet article qu'elles n'aident pas, mais interfèrent seulement avec la perception (l'image est cliquable)Cela ne vaut pas la peine de faire un longrid avec un tas d'effets de la documentation, mais vous devez considérer les règles de base.
Disposition . Définissez la largeur du texte principal, la police, la taille, les en-têtes et les retraits. Engagez un designer et, pour accepter un travail ou le faire vous-même, lisez le livre Typographie et mise en page d'Artyom Gorbunov. Il ne présente qu'une des vues de la mise en page, mais c'est assez.
Allocations . Définissez ce qui doit être souligné dans le texte. Il s'agit généralement du chemin dans l'interface, des boutons, des insertions de code, des fichiers de configuration, des blocs «Faites attention». Définissez la sélection de ces éléments et corrigez-la dans le planning. Gardez à l'esprit que moins il y a d'excrétion, mieux c'est. Quand il y en a beaucoup, le texte «fait du bruit». Même les guillemets créent du bruit s'ils sont utilisés trop souvent.
Captures d'écran Arrangez-vous avec l'équipe dans quels cas des captures d'écran sont nécessaires. Il n'est certainement pas nécessaire d'illustrer chaque étape. Un grand nombre de captures d'écran, dont les boutons individuels interfèrent avec la perception, gâchent la disposition. Déterminez la taille, ainsi que le format des sélections et légendes dans les captures d'écran, corrigez dans le règlement. N'oubliez pas que les illustrations doivent toujours être écrites et pertinentes. Encore une fois, si le produit est régulièrement mis à jour, il sera difficile de garder une trace de chacun.
La longueur du texte . Évitez les articles trop longs. Fragmentez-les en parties et, si cela n'est pas possible, ajoutez du contenu lié à une ancre en haut de l'article. Un moyen simple de raccourcir visuellement un article consiste à masquer les détails techniques nécessaires à un cercle restreint de lecteurs sous un becquet.
Les formats Combinez plusieurs formats dans des articles: texte, vidéo et images. Cela améliorera la perception.
N'essayez pas de masquer les problèmes avec une belle mise en page. Honnêtement, nous espérions nous-mêmes que le "wrapper" sauverait la documentation obsolète - cela n'a pas fonctionné. Les textes avaient tellement de bruit visuel et de détails inutiles que la réglementation et le nouveau design étaient impuissants.
Une grande partie de ce qui précède sera déterminée par le site que vous utilisez pour la documentation. Pour nous, par exemple, c'est Confluence. Il a également dû bricoler. Si vous êtes intéressé, lisez l'histoire de notre développeur Web:
Confluence pour une base de connaissances publique: changez la conception et configurez la séparation des langues .
Où commencer à s'améliorer et comment survivre
Si votre documentation est aussi vaste que celle d’ISPsystem et que vous ne savez pas quoi récupérer, commencez par les problèmes les plus graves. Les clients ne comprennent pas comment améliorer les textes, prendre des règlements et former des rédacteurs. La documentation est obsolète - prenez en charge les processus internes. Commencez par les articles les plus populaires sur les produits les plus recherchés: demandez de l'aide, consultez les analyses de site Web et les requêtes des moteurs de recherche.
Disons tout de suite - ce ne sera pas facile. Et rapidement aussi, il est peu probable qu'il réussisse. À moins que vous ne commenciez et que vous ne fassiez tout de suite. Nous savons une chose avec certitude - elle s'améliorera avec le temps. Mais le processus ne s'arrêtera jamais :-).