Documentation et base de connaissances

Ce que couvre cette catégorie

Des endroits pour mettre les choses par écrit afin que d’autres les retrouvent : centres d’aide destinés aux clients, guides internes, documentation pour développeurs et la recherche qui rend tout cela utile.

La distinction qui compte est le public. La documentation destinée aux clients demande une adresse publique, un processus de relecture et un langage écrit pour quelqu’un qui est déjà bloqué. La documentation destinée au personnel peut être plus brouillonne et demande plutôt des droits d’accès.

Les connaissances personnelles et celles des petites équipes relèvent de notes et wiki. La file de tickets où arrivent les questions restées sans réponse, c’est le support client.

La structure décide si l’on trouve quoi que ce soit

Tout projet de documentation commence organisé et finit en tas. L’outillage ralentit ou accélère cette pente.

Regardez comment fonctionne la hiérarchie : catégories, sous-pages, renvois, et si une page peut se trouver à deux endroits sans être dupliquée. Regardez ensuite ce qui se passe à trois cents pages, là où une navigation conçue pour trente s’effondre.

La recherche est le test honnête. Essayez une requête avec les mots qu’un client emploierait plutôt que votre vocabulaire interne. Les produits qui ne trouvent que les titres échoueront à ce test, et les lecteurs finiront dans votre file de support.

Les étiquettes et les suggestions d’articles liés aident quand elles sont entretenues. Personne ne les entretient longtemps à la main : préférez les produits qui génèrent les liens à partir du contenu.

Écrire, relire et garder les pages exactes

La documentation moisit en silence. Une page exacte en mars devient un ticket de support en septembre, sans que rien en elle ne semble faux.

Les produits utiles portent un responsable, des dates de revue et un tampon de dernière vérification que le lecteur peut voir. Les états de brouillon et le circuit de relecture comptent dès que plus de deux personnes écrivent, et l’historique des versions compte la première fois que quelqu’un demande ce que disait une page avant son changement.

La réutilisation vaut aussi la peine d’être vérifiée. Une limite, un prix ou une liste de versions prises en charge doivent exister une seule fois et être inclus partout où ils apparaissent, au lieu d’être collés dans onze pages qui se contrediront d’ici le trimestre prochain.

Publication et question du référencement

Un centre d’aide public est un site web, et il doit se comporter comme tel.

• URL propres qui survivent à une réorganisation, avec des redirections quand ce n’est pas possible.
• Titres et descriptions modifiables par article, et non générés à partir de la première ligne.
• Pages rapides, sans lourde application à charger avant que le texte apparaisse.
• Plans de site mis à jour à la publication plutôt que selon un calendrier dont personne ne se souvient.
• Un domaine personnalisé, pour que le contenu bâtisse l’autorité de votre propre site et non celle de l’éditeur.

Ce dernier point mérite d’être défendu en interne. La documentation est souvent le contenu le plus performant d’un éditeur de logiciel, et l’héberger sur un sous-domaine de prestataire donne ce trafic à d’autres.

Mesure, et la seule mesure qui compte

Les pages vues n’apprennent presque rien. Deux chiffres apprennent beaucoup.

Le premier est le nombre de recherches sans résultat utile, qui forme une liste écrite de ce qu’il faut créer ensuite. Le second est de savoir si les lecteurs qui ont ouvert un article ont quand même contacté le support ensuite, ce qui demande de relier le centre d’aide à votre système de tickets.

Réécrivez à partir de cette liste plutôt que d’opinions. Les cinq articles qui échouent le plus souvent valent plus d’attention que cinquante que personne ne visite.

Comment ces produits sont tarifés

Des postes pour les auteurs, parfois la lecture gratuite pour tous, parfois un tarif par lecteur interne inscrit. Les centres d’aide publics facturent généralement par auteur et par volume d’articles, les wikis internes par utilisateur.

Surveillez trois frontières. Domaines personnalisés, versionnement et authentification unique se trouvent chacun au-dessus de la formule d’entrée. La profondeur de l’analytique en est une quatrième. Les éditeurs qui regroupent un centre d’aide avec un produit de support le tarifient souvent en option au lieu de l’inclure, ce qui fait partie des habitudes rassemblées dans ce que cachent les pages de tarifs.

Avant de vous engager, exportez tout et lisez le résultat. Du Markdown ou un balisage propre signifie que vous pouvez partir. Un format propriétaire signifie que l’archive est prise en otage.

Créer un centre d’aide à partir de rien

La première version doit être gênamment petite.

Prenez les vingt questions que reçoit le plus souvent votre file de support et répondez-y correctement. Cela couvre la majorité des contacts et prend une semaine, alors que planifier d’abord une structure complète prend un trimestre et ne répond à rien entre-temps.

Écrivez chaque article pour quelqu’un qui est déjà bloqué, c’est-à-dire la réponse d’abord et l’explication ensuite. Les captures d’écran vieillissent mal : servez-vous-en là où elles aident vraiment et attendez-vous à les remplacer.

Laissez ensuite la structure émerger. Après trente articles, les catégories deviennent évidentes, et les imposer dès le cinquième oblige à tout réorganiser de toute façon.

Publiez les termes de recherche sans résultat comme file d’attente d’écriture. C’est le seul plan de contenu de cette catégorie qui ne s’épuise jamais et ne se trompe jamais.