Rédiger des articles de centre d'aide que vos clients utilisent vraiment
Quelqu’un tape « exporter les factures » dans la recherche de votre centre d’aide. Il obtient trois résultats : « Présentation de la facturation », « Rapports » et « Premiers pas avec les données ». Aucun ne parle d’export. Il ferme l’onglet et vous écrit un e-mail.
C’est le problème de la plupart des articles de centre d’aide. Ils sont organisés selon la façon dont le produit est construit, pas selon ce que les gens essaient de faire.
Voici donc la réponse courte. Pour rédiger des articles de centre d’aide que les gens utilisent vraiment : nommez chaque article d’après une seule tâche, dans les mots du client ; dites en une ligne ce qu’il permet de faire ; listez ce qu’il faut préparer d’abord ; donnez des étapes numérotées, une action par étape ; ajoutez une capture d’écran là où les gens se perdent d’habitude ; et terminez par ce qu’ils doivent voir quand tout a fonctionné. Un article, une tâche. Si vous vous surprenez à écrire « vous pouvez aussi », c’est probablement un deuxième article.
Le reste de cet article détaille tout cela : un modèle à copier, une réécriture avant et après, ce qu’il faut écrire en premier et comment éviter que tout devienne obsolète six semaines après le lancement.
Qu’est-ce qui fait un bon article de base de connaissances ?
Personne ne lit la documentation d’aide pour le plaisir. Les gens arrivent en pleine tâche, un peu agacés, en général depuis une recherche (la vôtre ou celle de Google) ou depuis un lien qu’un membre de votre équipe a collé dans une réponse. Ils parcourent le texte en diagonale. Ils veulent trouver l’étape 3, la faire et repartir.
Un bon article de base de connaissances est donc un article qui permet à une personne pressée et un peu agacée de terminer sa tâche sans rien lire deux fois. En pratique, cela signifie :
- Un article, une tâche. « Inviter un collègue » et « Modifier le rôle d’un collègue » sont deux articles. Ils renvoient l’un vers l’autre.
- Les titres ressemblent à des requêtes de recherche. Les gens cherchent avec des verbes : « résilier l’abonnement », « réinitialiser le mot de passe », « connecter Slack ». Vos titres doivent se lire de la même façon.
- Les étapes sont numérotées et atomiques. Un clic ou un champ par étape. Si une étape contient « puis », scindez-la.
- Les intitulés exacts de l’interface, en gras. Si le bouton affiche Ajouter un membre, n’écrivez pas « cliquez sur le bouton d’invitation ». Le lecteur rapproche les mots de l’écran de ceux de votre article.
- L’article se termine par un résultat. « Ils apparaîtront dans la liste des membres avec un badge En attente tant qu’ils n’auront pas accepté. » Cette ligne indique aux gens qu’ils ont terminé, et c’est celle que la plupart des rédacteurs oublient.
Le cadre Diátaxis répartit la documentation en tutoriels, guides pratiques, références et explications. La plupart des articles de centre d’aide doivent être des guides pratiques. L’erreur classique est de mélanger les quatre sur une même page, si bien que celui qui cherche l’étape 4 doit traverser trois paragraphes sur la raison d’être de la fonctionnalité.
Un modèle d’article de centre d’aide à copier
C’est le modèle à partir duquel je commencerais chaque article de tâche. Il fonctionne dans Zendesk, Intercom, Help Scout, GitBook, ou dans un dossier de fichiers Markdown de votre dépôt.
# [Verb] [the thing]
<!-- e.g. "Export your invoices to CSV" -->
[One or two sentences: what this does and when you'd want it.
Mention the plan or role if it's restricted.]
**Before you start**
- You need [role or permission], e.g. Admin or Owner
- [Anything to have ready: a file, an API key, a connected account]
## Steps
1. Go to **[Page name]** in the left sidebar.
2. Click **[Exact button label]**.
3. In **[Field name]**, enter [what, with an example value].
4. Click **[Confirm button label]**.
<!-- Screenshot of the step where people get stuck.
Crop to the relevant area, highlight the target. -->
## What happens next
[What they'll see when it worked. How long it takes.
Who gets notified.]
## If it didn't work
- **[Symptom in the customer's words]**: [cause and fix]
- **[Second most common symptom]**: [cause and fix]
## Related
- [The task people usually do next]
- [The reverse task, e.g. "Remove a teammate"]
Quelques remarques pour l’utiliser.
L’introduction n’est pas un argumentaire commercial. « Notre puissante fonction d’export vous donne un contrôle total sur vos données » n’apprend rien au lecteur. « Téléchargez toutes les factures d’une période dans un fichier CSV que vous pouvez ouvrir dans Excel ou Google Sheets » lui dit s’il est sur la bonne page.
« Avant de commencer » évite le plus de tickets. L’échec classique : quelqu’un suit six étapes, puis découvre à la septième que seuls les administrateurs peuvent le faire. Placez les autorisations et les limites d’offre en haut, pas dans une note en bas.
« Si cela n’a pas fonctionné » doit venir de vrais tickets. N’inventez pas de dépannage. Parcourez le dernier mois d’e-mails de support et notez ce qui a réellement bloqué les gens. Deux ou trois éléments suffisent. Si vous voulez une méthode reproductible pour cela, nous avons rédigé un guide à part sur la transformation des tickets de support en articles d’aide.
Avant et après : réécrire un article d’aide typique
Voici le genre d’article qu’on écrit la semaine où une fonctionnalité sort. Le produit est inventé, le schéma ne l’est pas.
Gestion de l’équipe
Notre fonctionnalité de gestion d’équipe facilite la collaboration. Depuis la zone Paramètres, vous pouvez gérer votre équipe, notamment ajouter de nouveaux membres via l’onglet Membres, où vous trouverez le bouton Ajouter un membre, et choisir des rôles comme Administrateur, Éditeur ou Lecteur, qui déterminent ce à quoi chacun a accès. Les utilisateurs invités reçoivent un e-mail. Notez que seuls les administrateurs peuvent ajouter des membres et que le nombre de places dépend de votre offre.
Tout ce dont le lecteur a besoin s’y trouve. Mais dans le mauvais ordre, sous un titre que personne ne cherche, et la restriction d’autorisation est la dernière phrase.
Voici la réécriture :
Inviter un collègue
Ajoutez quelqu’un à votre espace de travail pour qu’il puisse consulter et modifier les projets.
Avant de commencer : vous devez être administrateur. Chaque personne occupe une place de votre offre. Vous pouvez voir combien il vous en reste dans Paramètres > Facturation.
- Allez dans Paramètres > Membres.
- Cliquez sur Ajouter un membre.
- Saisissez son adresse e-mail.
- Choisissez un rôle : Administrateur, Éditeur ou Lecteur.
- Cliquez sur Envoyer l’invitation.
Ce qui se passe ensuite : la personne reçoit une invitation par e-mail. Tant qu’elle n’a pas accepté, elle apparaît dans la liste des membres avec un badge En attente.
Si cela n’a pas fonctionné : si Ajouter un membre est grisé, vous avez utilisé toutes vos places. Retirez quelqu’un ou ajoutez des places dans Paramètres > Facturation.
Mêmes faits, longueur à peu près identique. Mais le titre correspond à ce que les gens tapent, la restriction est en tête, chaque étape est une seule action, et le lecteur sait quand il a terminé. Les explications sur les rôles sont passées dans un court article à part (« Ce que peut faire chaque rôle »), auquel renvoie l’étape 4.
Quelle longueur pour un article de centre d’aide ?
Aussi long que la tâche, pas plus. En règle générale, un guide pratique à tâche unique tient en 150 à 500 mots environ. Si vous êtes bien au-delà, vérifiez si vous n’avez pas collé deux tâches ensemble ou dérivé vers l’explication de la philosophie de la fonctionnalité.
L’exception, ce sont les guides de configuration, comme « Connecter votre boutique Shopify », qui comptent réellement une douzaine d’étapes réparties sur deux systèmes. Ceux-là peuvent être longs, à condition de les découper en sections H2 vers lesquelles on peut sauter.
Où les captures d’écran aident, et où elles nuisent
Les captures d’écran sont ce que les lecteurs remarquent le plus et ce que les équipes entretiennent le moins.
Utilisez-en une quand l’interface est ambiguë : une page de paramètres chargée, une fenêtre modale à six champs, un bouton qui n’est pas là où on l’attend. Évitez-les pour « cliquez sur Enregistrer ». Recadrez au plus près de la zone qui compte et mettez la cible en évidence si l’écran est chargé.
Le piège est que chaque capture d’écran promet que l’interface ressemble encore à cela. Déplacez un menu et des dizaines d’articles montrent discrètement aux clients un écran qui n’existe plus. C’est le principal argument pour les automatiser plutôt que de les faire à la main. Nous avons comparé les options (scripts Playwright, enregistreurs d’écran, outils qui les capturent pour vous) dans comment créer automatiquement des captures d’écran de votre produit.

Quoi écrire en premier
Si vous partez de zéro, n’essayez pas de documenter chaque fonctionnalité. Écrivez dans cet ordre :
- Les quinze premières minutes. L’inscription, la première étape de configuration, le premier moment « ah, c’est utile ». Chaque nouvel utilisateur lit ces articles.
- Vos principales questions de support. Parcourez votre boîte de réception. Tout ce à quoi vous avez répondu trois fois ce mois-ci mérite un article.
- Tout ce qui touche à l’argent ou aux données. Changements de facturation, résiliation, suppression, export. Les gens sont inquiets ici et veulent de la certitude, pas un paragraphe vague.
- Les intégrations. Connecter des comptes tiers est l’endroit où l’on se bloque sur des écrans que vous ne contrôlez pas.
- Tout le reste, à peu près par ordre de fréquence de rencontre.
Regroupez-les en une poignée de collections nommées comme les clients réfléchissent : « Premiers pas », « Facturation et compte », « Utiliser [votre fonctionnalité principale] », « Intégrations », « Dépannage ». Évitez les collections qui reflètent la structure de vos équipes internes.

Rédiger de la documentation d’aide : les petites habitudes qui comptent
- Écrivez à la deuxième personne et au présent : « Cliquez », « Vous verrez ».
- Utilisez les vrais intitulés du produit, même ceux que vous jugez mal choisis. Puis allez corriger l’intitulé.
- Limitez les paragraphes à deux ou trois phrases.
- Utilisez les encadrés avec parcimonie. Une note pour une information utile, un avertissement pour une action irréversible. Si chaque article contient trois avertissements, les gens cessent de les voir.
- Affichez la date de dernière mise à jour de l’article, pour que les lecteurs (et vous) voient à quel point il est récent.
- Faites des liens vers la suite. Chaque article doit renvoyer vers ce que les gens font généralement ensuite.
Le guide de style de la documentation pour développeurs de Google vise la documentation technique, mais la plupart de ses conseils sur la clarté et le ton valent tout autant pour l’aide destinée aux clients.
Ce que personne ne planifie : garder les articles exacts
Rédiger l’article est la partie facile. Le plus difficile, c’est que votre produit change chaque semaine et pas votre centre d’aide.
Quel que soit l’outil, quelques pratiques aident :
- Étiquetez chaque article avec la fonctionnalité ou l’écran qu’il couvre, pour savoir exactement quels articles vérifier quand cette fonctionnalité change.
- Faites de « documentation vérifiée » un critère d’achèvement pour toute pull request qui modifie un texte d’interface ou un parcours utilisateur.
- Relisez vos articles les plus consultés environ une fois par mois. C’est là qu’une capture d’écran périmée fait le plus de dégâts.
- Surveillez les recherches qui ne renvoient rien. C’est une liste gratuite d’articles que vous n’avez pas encore écrits.
Nous traitons cela en détail dans comment garder votre documentation à jour, y compris comment relier la relecture de la documentation à votre processus de livraison. Et si vous publiez des notes de version, la même discipline s’applique : voir comment rédiger un changelog que vos clients lisent vraiment.
Où se place Ellie Docs
Transparence : nous développons un outil pour cela. Ellie Docs se connecte à votre dépôt GitHub, lit le code pour déterminer vos fonctionnalités et vos écrans visibles par les utilisateurs, et rédige un centre d’aide complet. Il exécute votre application dans un bac à sable, capture de vraies captures d’écran du produit connecté et les place dans les articles.

La partie qui me tient le plus à cœur, c’est la maintenance. Quand une pull request est fusionnée, Ellie vérifie quels articles sont concernés par la modification et propose des corrections sous forme de diff que vous acceptez ou rejetez. Rien ne se publie tout seul. Vous décidez toujours de ce que lisent les clients, mais vous cessez d’apprendre par un ticket de support que l’étape 6 est fausse depuis un mois.
Si vous avez déjà un centre d’aide, Ellie Docs importe vos articles existants sous forme de brouillons pour que vous ne partiez pas de zéro. Il existe une offre gratuite, sans carte bancaire.
Et si vous préférez tout faire à la main, le modèle ci-dessus fonctionne très bien seul.
Quelques questions fréquentes
Quelle est la différence entre un centre d’aide et une base de connaissances ? Pas grand-chose, en pratique. « Base de connaissances » désigne généralement l’ensemble des articles, et « centre d’aide » le site destiné aux clients, avec la recherche et la navigation par-dessus. La plupart des outils emploient les deux termes indifféremment.
Qui doit rédiger les articles d’aide : le support, le produit ou l’ingénierie ? Celui qui est le plus proche des questions. Le support sait ce qui déroute les gens, l’ingénierie sait ce qui a changé. Une organisation qui fonctionne bien : le support est responsable du centre d’aide, et les ingénieurs signalent les articles concernés dans leurs pull requests.
Vous voulez un premier brouillon de votre centre d’aide rédigé à partir de votre propre base de code ? Essayez Ellie Docs gratuitement et voyez ce qu’il produit à partir de votre dépôt.