/kb-article

Si vous voyez des placeholders qui ne vous sont pas familiers ou si vous devez vérifier quels outils sont connectés, consultez CONNECTORS.md.

Rédigez un article de base de connaissances prêt pour publication à partir d'un problème de support résolu, d'une question courante ou d'une solution documentée. Structure le contenu pour optimiser sa découverte et l'auto-assistance.

Utilisation

/kb-article <problème résolu, référence de ticket ou description de sujet>

Exemples :

• /kb-article Comment configurer SSO avec Okta — résolu pour 3 clients le mois dernier
• /kb-article Ticket #4521 — client n'a pas pu exporter les données au-delà de 10 k lignes
• /kb-article Question courante : comment configurer les notifications webhook
• /kb-article Problème connu : les graphiques du tableau de bord ne se chargent pas sur Safari 16

Workflow

1. Comprendre le document source

Analysez l'entrée pour identifier :

• Quel était le problème ? Le problème initial, la question ou l'erreur
• Quelle était la solution ? La résolution, la solution de contournement ou la réponse
• À qui cela s'adresse-t-il ? Type d'utilisateur, niveau d'offre ou configuration
• Quelle est la fréquence de cet événement ? Problème ponctuel ou récurrent
• Quel type d'article convient le mieux ? How-to, dépannage, FAQ, problème connu ou référence (voir types d'articles ci-dessous)

Si une référence de ticket est fournie, consultez le contexte complet :

• ~~plateforme support : Récupérez le fil de discussion du ticket, la résolution et les notes internes
• ~~base de connaissances : Vérifiez si un article similaire existe déjà (mise à jour ou création nouvelle)
• ~~suivi de projet : Vérifiez s'il existe un bug ou une demande de fonctionnalité associés

2. Rédiger l'article

Utilisez la structure d'article, les normes de formatage et les bonnes pratiques de découverte ci-dessous :

• Suivez le modèle pour le type d'article choisi (how-to, dépannage, FAQ, problème connu ou référence)
• Appliquez les bonnes pratiques de découverte : titre en langage client, phrase d'ouverture en langage simple, messages d'erreur exacts, synonymes courants
• Maintenez la lisibilité : en-têtes, étapes numérotées, paragraphes courts

3. Générer l'article

Présentez le brouillon avec les métadonnées :

## Brouillon d'article KB

**Titre :** [Titre de l'article]
**Type :** [How-to / Dépannage / FAQ / Problème connu / Référence]
**Catégorie :** [Domaine produit ou sujet]
**Étiquettes :** [Étiquettes de recherche]
**Audience :** [Tous les utilisateurs / Administrateurs / Développeurs / Offre spécifique]

---

[Contenu complet de l'article — utilisant le modèle approprié ci-dessous]

---

### Notes de publication
- **Source :** [Ticket #, conversation client ou discussion interne]
- **Articles existants à mettre à jour :** [S'il y a chevauchement avec du contenu existant]
- **Révision nécessaire de la part de :** [Expert métier ou équipe si la précision technique doit être vérifiée]
- **Date de révision suggérée :** [Quand le réviser pour en assurer la précision]

4. Proposer les étapes suivantes

Après avoir généré l'article :

• « Voulez-vous que je vérife si un article similaire existe déjà dans votre ~~base de connaissances ? »
• « Devrais-je ajuster le niveau technique pour une audience différente ? »
• « Voulez-vous que je rédige un article complémentaire (par exemple, un how-to pour accompagner ce guide de dépannage) ? »
• « Devrais-je créer une version réservée en interne avec des détails techniques supplémentaires ? »

Structure et normes de formatage des articles

Éléments universels d'un article

Chaque article KB doit inclure :

1. Titre : Clair, recherchable, décrivant le résultat ou le problème (pas de jargon interne)
2. Vue d'ensemble : 1-2 phrases expliquant ce que couvre cet article et à qui il s'adresse
3. Corps : Contenu structuré adapté au type d'article
4. Articles associés : Liens vers du contenu complémentaire pertinent
5. Métadonnées : Catégorie, étiquettes, audience, date de dernière mise à jour

Règles de formatage

• Utiliser les en-têtes (H2, H3) pour scinder le contenu en sections lisibles
• Utiliser les listes numérotées pour les étapes séquentielles
• Utiliser les listes à puces pour les éléments non-séquentiels
• Utiliser le gras pour les noms d'éléments d'interface, les termes clés et les emphases
• Utiliser les blocs de code pour les commandes, appels API, messages d'erreur et valeurs de configuration
• Utiliser les tableaux pour les comparaisons, les options ou les données de référence
• Utiliser des callouts/notes pour les avertissements, conseils et mises en garde importantes
• Garder les paragraphes courts — 2-4 phrases maximum
• Une idée par section — si une section couvre deux sujets, la diviser

Rédaction pour la découverte

Les articles sont inutiles si les clients ne les trouvent pas. Optimisez chaque article pour la recherche :

Bonnes pratiques de titres

Optimisation des mots-clés

• Inclure les messages d'erreur exacts — les clients copient-collent le texte d'erreur dans la recherche
• Utiliser le langage client, pas la terminologie interne — « impossible de se connecter » et non « échec d'authentification »
• Inclure les synonymes courants — « supprimer/enlever », « tableau de bord/page d'accueil », « exporter/télécharger »
• Ajouter des formulations alternatives — aborder le même problème sous différents angles dans la vue d'ensemble
• Étiqueter par domaines produit — s'assurer que la catégorie et les étiquettes correspondent à la façon dont les clients pensent le produit

Formule de phrase d'ouverture

Commencez chaque article par une phrase qui reformule le problème ou la tâche en langage simple :

• How-to : « Ce guide vous montre comment [accomplir X]. »
• Dépannage : « Si vous voyez [symptôme], cet article explique comment le corriger. »
• FAQ : « [Question dans les termes du client] ? Voici la réponse. »
• Problème connu : « Certains utilisateurs connaissent [symptôme]. Voici ce que nous savons et comment contourner le problème. »

Modèles de types d'articles

Articles How-to

Objectif : Instructions étape par étape pour accomplir une tâche.

Structure :

# Comment [accomplir tâche]

[Vue d'ensemble — ce que couvre ce guide et quand l'utiliser]

## Prérequis
- [Ce qui est nécessaire avant de commencer]

## Étapes
### 1. [Action]
[Instruction avec détails spécifiques]

### 2. [Action]
[Instruction]

## Vérifier que cela a fonctionné
[Comment confirmer le succès]

## Problèmes courants
- [Problème] : [Solution]

## Articles associés
- [Liens]

Bonnes pratiques :

• Commencer chaque étape par un verbe
• Inclure le chemin spécifique : « Allez à Paramètres > Intégrations > Clés API »
• Mentionner ce que l'utilisateur devrait voir après chaque étape (« Vous devriez voir une bannière de confirmation verte »)
• Tester les étapes vous-même ou vérifier avec une résolution de ticket récente

Articles de dépannage

Objectif : Diagnostiquer et résoudre un problème spécifique.

Structure :

# [Description du problème — ce que l'utilisateur voit]

## Symptômes
- [Ce que l'utilisateur observe]

## Cause
[Pourquoi cela se produit — explication brève, sans jargon]

## Solution
### Option 1 : [Correction principale]
[Étapes]

### Option 2 : [Alternative si l'option 1 ne fonctionne pas]
[Étapes]

## Prévention
[Comment éviter cela à l'avenir]

## Vous avez toujours un problème ?
[Comment obtenir de l'aide]

Bonnes pratiques :

• Commencer par les symptômes, pas les causes — les clients recherchent ce qu'ils voient
• Fournir plusieurs solutions quand c'est possible (correction la plus probable en premier)
• Inclure une section « Vous avez toujours un problème ? » qui oriente vers le support
• Si la cause racine est complexe, garder l'explication destinée au client simple

Articles FAQ

Objectif : Réponse rapide à une question courante.

Structure :

# [Question — dans les termes du client]

[Réponse directe — 1-3 phrases]

## Détails
[Contexte supplémentaire, nuance ou explication si nécessaire]

## Questions associées
- [Lien vers FAQ associée]
- [Lien vers FAQ associée]

Bonnes pratiques :

• Répondre à la question dans la première phrase
• Garder cela concis — si la réponse a besoin d'une procédure, c'est un how-to, pas une FAQ
• Regrouper les FAQ associées et créer des liens entre elles

Articles de problèmes connus

Objectif : Documenter un bug ou une limitation connus avec une solution de contournement.

Structure :

# [Problème connu] : [Brève description]

**Statut :** [En cours d'investigation / Solution de contournement disponible / Correction en cours / Résolu]
**Affecté :** [Qui/quoi est affecté]
**Dernière mise à jour :** [Date]

## Symptômes
[Ce que les utilisateurs vivent]

## Solution de contournement
[Étapes pour contourner le problème, ou « Aucune solution de contournement disponible »]

## Calendrier de correction
[Date de correction prévue ou statut actuel]

## Mises à jour
- [Date] : [Mise à jour]

Bonnes pratiques :

• Garder le statut à jour — rien n'érode la confiance plus vite qu'un article de problème connu obsolète
• Mettre à jour l'article quand la correction est diffusée et marquer comme résolu
• Si résolu, garder l'article en ligne pendant 30 jours pour les clients qui recherchent encore les anciens symptômes

Cadence d'examen et de maintenance

Les bases de connaissances se dégradent sans maintenance. Suivez ce calendrier :

Cycle de vie de l'article

1. Brouillon : Rédigé, en attente de révision
2. Publié : En ligne et disponible pour les clients
3. Nécessite mise à jour : Signalé pour révision (changement produit, retours d'expérience ou ancienneté)
4. Archivé : Ne s'applique plus mais conservé à titre de référence
5. Retiré : Supprimé de la base de connaissances

Quand mettre à jour ou créer un nouvel article

Mettre à jour existant quand :

• Le produit a changé et les étapes doivent être actualisées
• L'article est globalement correct mais manque un détail
• Les retours indiquent que les clients sont confus par une section spécifique
• Une meilleure solution de contournement ou solution a été trouvée

Créer nouveau quand :

• Une nouvelle fonctionnalité ou domaine produit a besoin de documentation
• Un ticket résolu révèle une lacune — aucun article n'existe pour ce sujet
• L'article existant couvre trop de sujets et devrait être divisé
• Une audience différente a besoin que la même information soit expliquée différemment

Taxonomie de liaison et de catégorisation

Structure de catégorie

Organiser les articles dans une hiérarchie qui correspond à la façon dont les clients pensent :

Premiers pas
├── Configuration de compte
├── Configuration initiale
└── Guides de démarrage rapide

Fonctionnalités et How-tos
├── [Domaine de fonctionnalité 1]
├── [Domaine de fonctionnalité 2]
└── [Domaine de fonctionnalité 3]

Intégrations
├── [Intégration 1]
├── [Intégration 2]
└── Référence API

Dépannage
├── Erreurs courantes
├── Problèmes de performance
└── Problèmes connus

Facturation et compte
├── Plans et tarification
├── Questions de facturation
└── Gestion de compte

Bonnes pratiques de liaison

• Lier le dépannage au how-to : « Pour les instructions de configuration, consultez [Comment configurer X] »
• Lier le how-to au dépannage : « Si vous rencontrez des erreurs, consultez [Dépannage de X] »
• Lier FAQ à des articles détaillés : « Pour une procédure complète, consultez [Guide de X] »
• Lier les problèmes connus aux solutions de contournement : Garder la chaîne du problème à la solution courte
• Utiliser les liens relatifs dans la KB — ils survivent mieux aux restructurations que les URL absolues
• Éviter les liens circulaires — si A s'attache à B, B ne devrait pas s'attacher à A sauf si les deux sont véritablement des points d'entrée utiles

Bonnes pratiques de rédaction KB

1. Rédiger pour le client frustré qui recherche une réponse — être clair, direct et utile
2. Chaque article doit être trouvable par recherche en utilisant les mots qu'un client taperait
3. Tester vos articles — suivez les étapes vous-même ou faites-les suivre par quelqu'un d'unfamilier avec le sujet
4. Garder les articles ciblés — un problème, une solution. Diviser si un article grandit trop
5. Maintenir agressivement — un article incorrect est pire qu'aucun article
6. Suivre ce qui manque — chaque ticket qui aurait pu être un article KB est une lacune de contenu
7. Mesurer l'impact — les articles qui ne reçoivent pas de trafic ou ne réduisent pas les tickets doivent être améliorés ou retirés