La documentation du logiciel n'est qu'un ensemble d'articles. Mais même eux peuvent vous rendre fou. Premièrement, vous passez beaucoup de temps à chercher les instructions nécessaires. Alors vous comprenez le texte obscur. Vous faites ce qui est écrit, mais le problème n'est pas résolu. Vous cherchez un autre article, vous devenez nerveux... Une heure plus tard, vous abandonnez tout et partez. C’est ainsi que fonctionne une mauvaise documentation. Qu'est-ce qui fait que c'est ainsi et comment y remédier - lisez sous la coupe.
Il y avait de nombreuses lacunes dans notre ancienne documentation. Nous le retravaillons depuis près d'un an maintenant afin que le scénario décrit ci-dessus n'affecte pas nos clients. Regarder, и .
Problème 1 : articles peu clairs et mal rédigés
Si la documentation est impossible à comprendre, à quoi ça sert ? Mais personne n’écrit volontairement des articles incompréhensibles. Ils se produisent lorsque l'auteur ne pense pas au public et au but, verse de l'eau et ne vérifie pas les erreurs dans le texte.
- Audience. Avant d’écrire un article, il faut réfléchir au niveau de préparation du lecteur. Il est logique que dans un article destiné à un débutant, vous ne deviez pas sauter les étapes de base et laisser les termes techniques sans explication, mais dans un article sur une fonctionnalité rare dont seuls les professionnels ont besoin, vous devez expliquer la signification du mot PHP.
- Objectif. Encore une chose à laquelle il faut penser à l'avance. L'auteur doit se fixer un objectif clair, déterminer l'effet utile de l'article et décider ce que le lecteur fera après l'avoir lu. Si cela n’est pas fait, vous vous retrouverez avec une description pour le plaisir de la description.
- L'eau et les insectes. Il y a beaucoup d'informations inutiles et de bureaucratie, les erreurs et les fautes de frappe interfèrent avec la perception. Même si le lecteur n’est pas un nazi en matière de grammaire, une négligence dans le texte peut le rebuter.
Tenez compte des conseils ci-dessus et les articles deviendront plus clairs - c'est garanti. Pour le rendre encore meilleur, utilisez notre .
Problème 2. Les articles ne répondent pas à toutes les questions
C'est mauvais lorsque la documentation ne suit pas le développement, ne répond pas aux vraies questions et que les erreurs qu'elle contient ne sont pas corrigées pendant des années. Il ne s’agit pas tant de problèmes d’auteur que d’organisation des processus au sein de l’entreprise.
La documentation ne suit pas le développement
La fonctionnalité est déjà disponible, le marketing prévoit de la couvrir, et il s'avère ensuite que le nouvel article ou la traduction ne figure toujours pas dans la documentation. Nous avons même dû reporter la sortie à cause de cela. Vous pouvez demander à tout le monde de confier les tâches aux rédacteurs techniques à temps autant que vous le souhaitez, mais cela ne fonctionnera pas. Si le processus n’est pas automatisé, la situation se répétera.
Nous avons apporté des modifications à YouTrack. La tâche de rédiger un article sur une nouvelle fonctionnalité incombe au rédacteur technique au moment même où la fonctionnalité commence à être testée. Ensuite, le marketing en prend connaissance afin de préparer la promotion. Les notifications arrivent également sur la messagerie 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
Nous avons l'habitude de travailler ainsi : une fonctionnalité est sortie, nous en avons parlé. Nous avons décrit comment l'allumer, l'éteindre et effectuer des réglages précis. Mais que se passe-t-il si un client utilise notre logiciel d'une manière à laquelle nous ne nous attendions pas ? Ou y a-t-il des erreurs auxquelles nous n'avons pas pensé ?
Afin de garantir que la documentation soit la plus complète possible, nous vous recommandons 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 seront transférés aux rédacteurs techniques afin qu'ils puissent compléter les articles existants ou en rédiger de nouveaux.
La documentation n'est pas améliorée
C’est difficile de le faire parfaitement tout de suite ; il y aura toujours des erreurs. Vous pouvez espérer des commentaires des clients, mais il est peu probable qu'ils signalent chaque faute de frappe, inexactitude, article incompréhensible ou introuvable. En plus des clients, les employés lisent la documentation, ce qui signifie qu'ils voient les mêmes erreurs. Cela peut être utilisé ! Il vous 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-t-il besoin d’un article, mais il n’existe pas ? Le testeur a-t-il remarqué l'inexactitude ? Le partenaire s'est-il plaint d'erreurs auprès des responsables du développement ? Tous dans ce groupe ! Les rédacteurs techniques corrigent certaines choses immédiatement, transfèrent certaines choses vers YouTrack et donnent à d'autres le temps de réfléchir. Pour éviter que le sujet ne s'éteigne, nous vous rappelons de temps en temps l'existence du groupe et l'importance du feedback.
Problème 3. Il faut beaucoup de temps pour trouver le bon article.
Un article introuvable ne vaut pas mieux qu’un article introuvable. La devise d’une bonne documentation devrait être « Facile à rechercher, facile à trouver ». Comment y parvenir ?
Organiser la structure et déterminer le principe de choix des thèmes. La structure doit être aussi transparente que possible afin que le lecteur ne se demande pas : « Où puis-je trouver cet article ? Pour résumer, il existe deux approches : depuis l'interface et depuis les tâches.
- Depuis l'interface. Le contenu duplique les sections du panneau. C'était le cas dans l'ancienne documentation du système ISP.
- Des 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 correspond à ce que recherchent les utilisateurs et qu'il est traité de manière à répondre spécifiquement à la question de l'utilisateur.
Mettre en place une recherche centralisée. Dans un monde idéal, la recherche devrait fonctionner même si vous faites une faute d’orthographe ou une erreur de langue. Notre recherche à Confluence jusqu'à présent ne peut pas nous plaire avec cela. Si vous possédez 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 sur la page principale fonctionne pour tous les produits, et si vous êtes déjà dans une section spécifique, alors uniquement pour les articles qu'elle contient.
Ajouter du contenu et du fil d'Ariane. C'est bien quand chaque page a un menu et un fil d'Ariane - le chemin de l'utilisateur vers la page actuelle avec la possibilité de revenir à n'importe quel niveau. Dans l'ancienne documentation du système ISP, vous deviez quitter l'article pour accéder au contenu. Ce n'était pas pratique, nous l'avons donc corrigé dans le nouveau.
Placer des liens dans le produit. Si les gens reviennent encore et encore avec la même question, il est logique d'ajouter un indice avec sa solution à l'interface. Si vous disposez de données ou d'informations sur le moment où un utilisateur rencontre un problème, vous pouvez également le notifier via une liste de diffusion. Montrez-leur votre inquiétude et soulagez le fardeau du soutien.
À droite dans la fenêtre contextuelle se trouve un lien vers un article sur la configuration de DNSSEC dans la section de gestion de domaine d'ISPmanager.
Configurer des références croisées dans la documentation. Les articles liés les uns aux autres doivent être « liés ». Si les articles sont séquentiels, veillez à ajouter des flèches avant et arrière à la fin de chaque texte.
Très probablement, une personne cherchera d'abord une réponse à sa question non pas auprès de vous, mais auprès d'un moteur de recherche. C'est dommage s'il n'y a pas de liens vers la documentation pour des raisons techniques. Alors prenez soin de l’optimisation des moteurs de recherche.
Problème 4. Une mise en page obsolète interfère avec la perception
En plus des mauvais textes, la documentation peut être gâchée par sa conception. Les gens sont habitués à lire des documents bien écrits. Blogs, réseaux sociaux, médias - tous les contenus sont présentés non seulement beaux, mais aussi faciles à lire et agréables à regarder. Par conséquent, vous pouvez facilement comprendre la douleur d’une personne qui voit du texte comme dans la capture d’écran ci-dessous.
Il y a tellement de captures d'écran et de points forts dans cet article qu'ils n'aident pas, mais interfèrent seulement avec la perception (l'image est cliquable)
Vous ne devriez pas faire une longue lecture de la documentation avec un tas d'effets, mais vous devez prendre en compte les règles de base.
Mise en page. Déterminez la largeur, la police, la taille, les titres et le remplissage du corps du texte. Embauchez un designer et pour accepter le travail ou le faire vous-même, lisez le livre d'Artyom Gorbunov « Typographie et mise en page ». Il ne présente qu’une seule vue du layout, mais c’est tout à fait suffisant.
Lotissement. Déterminez ce qui doit être souligné dans le texte. Il s'agit généralement d'un chemin dans l'interface, de boutons, d'insertions de code, de fichiers de configuration, de blocs « Veuillez noter ». Déterminez quelles seront les attributions de ces éléments et enregistrez-les dans le règlement. Gardez à l’esprit que moins il y a de décharges, mieux c’est. Lorsqu’ils sont nombreux, le texte est bruyant. Même les guillemets créent du bruit s’ils sont utilisés trop souvent.
Captures d'écran. Convenez 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, incl. boutons séparés, interfèrent avec la perception, gâchent la mise en page. Déterminez la taille, ainsi que le format des surlignages et des signatures sur les captures d'écran, et enregistrez-les dans le règlement. N'oubliez pas que les illustrations doivent toujours correspondre à ce qui est écrit et être pertinentes. Encore une fois, si le produit est mis à jour régulièrement, il sera difficile de suivre tout le monde.
Longueur du texte. Évitez les articles trop longs. Divisez-les en parties et, si cela n'est pas possible, ajoutez du contenu avec des liens d'ancrage au début de l'article. Un moyen simple de raccourcir visuellement un article consiste à cacher les détails techniques nécessaires à un cercle restreint de lecteurs sous un spoiler.
Formats. Combinez plusieurs formats dans vos articles : texte, vidéo et images. Cela améliorera la perception.
N'essayez pas de dissimuler les problèmes avec une belle mise en page. Honnêtement, nous espérions nous-mêmes que le "wrapper" sauvegarderait la documentation obsolète - cela n'a pas fonctionné. Les textes contenaient tellement de bruit visuel et de détails inutiles que les réglementations et la nouvelle conception étaient impuissantes.
Une grande partie de ce qui précède sera déterminée par la plate-forme que vous utilisez pour la documentation. Par exemple, nous avons Confluence. J'ai dû le bricoler aussi. Si vous êtes intéressé, lisez l’histoire de notre développeur web : .
Par où commencer à s'améliorer et comment survivre
Si votre documentation est aussi vaste que celle de votre FAI et que vous ne savez pas par où commencer, commencez par les plus gros problèmes. Les clients ne comprennent pas le document - améliorent les textes, élaborent des règlements, forment les rédacteurs. La documentation est obsolète – prenez soin des processus internes. Commencez par les articles les plus populaires sur les produits les plus populaires : demandez de l'aide, consultez les analyses du site et les requêtes dans les moteurs de recherche.
Disons-le tout de suite : ce ne sera pas facile. Et il est peu probable que cela fonctionne rapidement non plus. À moins que vous débutiez et que vous fassiez ce qu'il faut tout de suite. Une chose dont nous sommes sûrs, c’est que cela s’améliorera avec le temps. Mais le processus ne finira jamais :-).
Source: habr.com