Documentation d'assistance

Quand l'utiliser

Activez cette compétence quand un fondateur ou un membre de l'équipe doit créer une documentation orientée client qui aide les utilisateurs à résoudre des problèmes de manière autonome. Cela inclut des demandes comme « rédigez un article de centre d'aide », « créez une FAQ », « documentez notre API », « rédigez un guide de dépannage », « créez un guide de démarrage » ou « nos tickets de support posent toujours les mêmes questions ».

Contexte requis

À partir du contexte de startup : type de produit, niveau technique des utilisateurs cibles, documentation existante (le cas échéant), principales catégories de tickets de support, et outils utilisés pour l'hébergement de docs (p. ex., Notion, GitBook, Zendesk, ReadMe).
De la part de l'utilisateur : le sujet spécifique à documenter, le public cible (utilisateurs finaux, administrateurs, développeurs), le niveau de sophistication technique de l'utilisateur, les points de défaillance courants ou sources de confusion, et s'il s'agit d'un nouvel article ou d'une mise à jour du contenu existant.

Flux de travail

Identifier le type de document — Déterminez quel modèle convient : article de centre d'aide, FAQ, guide de dépannage, référence API, ou guide de démarrage. Chacun répond à une intention utilisateur différente.
Définir le point d'entrée de l'utilisateur — Comment quelqu'un trouvera-t-il ce document ? Requête de recherche, message d'erreur, lien d'agent de support, bouton d'aide in-app ? Cela détermine le titre et la première ligne.
Rédiger au format problème-solution — Commencez par le problème de l'utilisateur (dans ses mots), puis fournissez la solution. Ne commencez jamais par des explications sur l'architecture du produit.
Appliquer la divulgation progressive — Mettez la réponse la plus courante en premier. Regroupez les cas limites, options avancées et détails techniques dans des sections dépliables ou plus loin dans l'article.
Ajouter des éléments de recherche — Incluez les messages d'erreur exacts, noms de fonctionnalités et termes familiers que les utilisateurs recherchent. Répétez les termes clés naturellement.
Tester avec la « règle des 3 du matin » — Lisez l'article comme si vous étiez un utilisateur frustré à 3 du matin avec un flux de travail cassé. Vous amène-t-il à une solution en moins de 2 minutes ? Sinon, restructurez.
Lier les articles connexes — Ajoutez des liens « En relation » ou « Étapes suivantes » au bas pour maintenir les utilisateurs dans le flux en libre-service.

Format de sortie

Un document markdown suivant l'un des cinq modèles ci-dessous. Chaque doc d'assistance doit être scannable en moins de 30 secondes et résoluble en moins de 2 minutes.

Modèle 1 : Article de centre d'aide

# [Titre orienté action : « Comment X » ou « Configuration de Y »]

[Une phrase décrivant ce que cet article vous aide à faire.]

## Avant de commencer
- Prérequis ou permissions nécessaires

## Étapes
1. Étape d'action avec chemin UI spécifique (Paramètres > Intégrations > Slack)
2. Étape d'action suivante
   > **Remarque :** Appel important pour les erreurs courantes

## Questions fréquemment posées
**Q : Question courante sur cette fonctionnalité ?**
R : Réponse directe.

## Besoin d'aide supplémentaire ?
Contactez le support à [lien] ou discutez avec nous in-app.

Modèle 2 : Guide de dépannage

# Dépannage : [Problème dans les mots de l'utilisateur]

## Symptômes
Ce que l'utilisateur voit quand ce problème se produit (messages d'erreur exacts dans des blocs de code).

## Solution rapide
La solution qui fonctionne 80% du temps. Mettez cela en premier.

## Si cela n'a pas fonctionné
### Cause 1 : [Cause la plus courante]
Comment diagnostiquer → Comment corriger

### Cause 2 : [Deuxième cause la plus courante]
Comment diagnostiquer → Comment corriger

## Collectez des informations pour le support
Si aucune des solutions ci-dessus n'a fonctionné, rassemblez ces détails avant de contacter le support :
- [Point de données spécifique 1]
- [Point de données spécifique 2]

Modèle 3 : Page FAQ

Regroupez les questions par catégorie (Démarrage, Problèmes courants, Facturation). Chaque réponse est composée de 1-3 phrases avec un lien vers l'article complet si la réponse nécessite plus de détails.

Modèle 4 : Documentation API

Structure : endpoint + méthode, authentification, paramètres de requête (tableau avec nom/type/requis/description), exemple de requête (curl fonctionnel), exemples de réponse (succès + chaque code d'erreur), et limites de débit. Chaque extrait de code doit être copiable et fonctionnel.

Modèle 5 : Guide de démarrage

Structure : phrase d'accueil avec résultat et engagement de temps, 3-5 étapes séquentielles (chacune avec l'action et pourquoi cela importe), un moment de vérification (« vous devriez maintenant voir X »), et des liens « Étapes suivantes » vers les fonctionnalités plus avancées.

Cadres et meilleures pratiques

Modèle problème-solution-vérification

Chaque document d'assistance doit suivre cet arc :

Problème : Énoncez ce que l'utilisateur essaie de faire ou ce qui s'est mal passé (en utilisant son langage, pas le jargon interne).
Solution : Fournissez la correction ou les étapes, dans l'ordre, avec les chemins UI exacts et les résultats attendus à chaque étape.
Vérification : Dites à l'utilisateur comment confirmer que cela a fonctionné. « Vous devriez maintenant voir X sur la page Y. »

Principes de recherche

Le titre correspond à la requête de recherche. « Comment exporter les données en CSV » et non « Aperçu de la fonctionnalité d'exportation de données ».
Incluez les messages d'erreur mot pour mot. Si les utilisateurs voient Erreur 403 : Permissions insuffisantes, cette chaîne exacte doit figurer dans votre guide de dépannage.
Utilisez à la fois les termes techniques et familiers. Écrivez « authentification unique (SSO) » afin que les recherches « SSO » et « authentification unique » trouvent l'article.
Mettez la réponse en avant. Placez la solution dans les 100 premiers mots. Beaucoup d'utilisateurs ne font jamais défiler.

Règles de divulgation progressive

Niveau 1 (visible) : La réponse qui fonctionne pour 80% des utilisateurs.
Niveau 2 (dépliable) : Cas limites, configuration avancée, variations spécifiques à la plateforme.
Niveau 3 (lié) : Détails techniques approfondis, explications d'architecture, référence API complète.
Ne forcez jamais un utilisateur basique à parcourir du contenu avancé pour obtenir une réponse simple.

Style d'écriture et maintenance

Deuxième personne, présent. « Cliquez sur Enregistrer » et non « Vous allez cliquer sur Enregistrer ». « Vous pouvez » et non « Les utilisateurs peuvent ».
Chemins UI spécifiques. « Allez à Paramètres > Équipe > Permissions » et non « Naviguez vers vos paramètres d'équipe ».
Montrer, puis expliquer. Commencez par l'action, puis ajoutez le contexte. Les utilisateurs veulent d'abord résoudre, comprendre ensuite.
Terminologie cohérente. Si l'UI dit « Workspace », n'appelez jamais cela « Organisation » dans les docs.
Étiquetez et datez chaque article. Les docs obsolètes sont pires que pas de docs. Examinez-les à chaque sortie de produit.
Suivez le taux de déviation. Si un article d'aide ne réduit pas les tickets de support pour ce sujet, réécrivez-le.
Incluez un widget de feedback. « Cela a-t-il été utile ? Oui / Non » — routez les réponses « Non » vers le propriétaire des docs.

Compétences connexes

process-docs — Chaînez quand le sujet de support nécessite un SOP interne pour gérer les cas limites ou les escalades que la doc orientée client ne peut pas résoudre seule.
onboarding-flow — Chaînez lors de la création de guides de démarrage qui font partie de l'expérience d'intégration des nouveaux utilisateurs.

Exemples

Exemple 1 : Guide de dépannage

Utilisateur : « Les utilisateurs nous envoient constamment des e-mails disant qu'ils ne peuvent pas connecter leur intégration Slack. Rédigez un guide de dépannage. »

Bon extrait de sortie :

Dépannage : Intégration Slack ne se connecte pas

Symptômes

Quand vous cliquez sur « Connecter à Slack », vous voyez l'une de ces erreurs :

Authorization failed. Please try again.

La page se redirige vers Paramètres sans message de confirmation.

Slack s'ouvre mais affiche « This app is not approved by your workspace admin. »

Solution rapide

Essayez un navigateur différent. Les extensions de navigateur (notamment les bloqueurs de publicités) peuvent interférer avec la redirection OAuth. Ouvrez une fenêtre incognito/privée et réessayez.

Vérifiez vos permissions Slack. Vous devez être administrateur Slack ou propriétaire du workspace. Demandez à votre administrateur Slack de vous accorder la permission, ou qu'il complète la connexion.

Si cela n'a pas fonctionné

Cause : Restrictions du workspace Slack

Votre workspace Slack peut exiger une approbation administrateur pour les nouvelles applications.

Diagnostiquez : Si vous voyez « This app is not approved by your workspace admin », c'est la cause.

Correction : Demandez à votre administrateur Slack d'approuver notre application à Slack Admin > Apps > Manage > cherchez « [Nom du produit] » > Approve.

Exemple 2 : Documentation API

Utilisateur : « Documentez notre endpoint webhook. Il accepte les requêtes POST avec les données d'événement et retourne 200 en cas de succès. »

Bonne approche de sortie : Suivez le modèle API précisément. Incluez les détails d'authentification, chaque paramètre avec type et requis/optionnel, un exemple curl fonctionnel, tous les codes de réponse avec descriptions, les limites de débit, et une politique de relance. Les développeurs copieront-colleront à partir de cette doc, donc chaque extrait de code doit réellement fonctionner.

support-docs