Créer une base de connaissances

Hébergez votre base de connaissances interne sur Mintlify pour centraliser les informations de votre équipe, améliorer la recherche et réduire la charge de maintenance.

Une base de connaissances interne aide votre équipe à trouver des réponses et à maintenir une source de vérité. Si les informations de votre équipe sont réparties sur différents canaux et plateformes, il est possible que l’on trouve des informations inexactes ou qu’on ne trouve rien du tout lors d’une recherche. Une base de connaissances centralisée résout ce problème en plaçant les réponses là où tout le monde peut les trouver et en donnant à votre équipe un endroit précis pour consigner les connaissances partagées.

Mintlify fournit l’infrastructure pour des bases de connaissances auxquelles toute votre équipe peut contribuer.

• Recherche optimisée par l’IA : L’assistant répond aux questions en utilisant le contenu de votre base de connaissances, afin que chacun puisse trouver des réponses sans savoir exactement où chercher.
• Intégrations Slack : Ajoutez l’assistant à Slack pour que votre équipe puisse poser des questions et utilisez l’agent pour capturer les connaissances issues des conversations.
• Contributions simplifiées : Le web editor et l’agent permettent à n’importe quel membre de votre équipe de mettre à jour le contenu sans apprendre Git ou Markdown.
• Authentification intégrée : Contrôlez l’accès avec SSO ou OAuth, et utilisez les groupes pour afficher des contenus différents selon les équipes.

​

Prérequis

Si vous n’avez pas encore créé de projet Mintlify, consultez le Quickstart pour déployer votre site.

• Un système d’authentification (SSO ou fournisseur OAuth comme Okta ou Azure AD)
• Le contrôle de votre domain pour l’hébergement
• Un accès administrateur à votre organisation Mintlify

​

Migrer le contenu existant

Si vous créez une base de connaissances à partir de zéro, passez directement à Concevoir la structure de la navigation.

​

Auditer le contenu existant

Dressez un inventaire du contenu actuellement présent dans votre base de connaissances existante. Cela vous permet de comprendre quel contenu migrer, de planifier son organisation dans votre nouvelle base de connaissances, d’identifier les lacunes dans votre contenu et de confirmer que vous avez bien transféré l’ensemble de votre contenu vers votre nouvelle base de connaissances.

• Nombre total d’articles : Aide à estimer l’effort nécessaire à la migration et à suivre l’exhaustivité.
• Sujets et contenu : Sert de base à la structure de votre navigation et à l’organisation de votre contenu.
• Organisation actuelle : Permet de voir comment votre contenu est actuellement organisé et si cela correspond à la structure souhaitée.
• Types de contenu : Permet de déterminer les besoins éventuels de conversion pour le texte, les PDF, les vidéos et le contenu intégré.
• Metadata : Repérez toute metadata à conserver, comme les dates, les auteurs et les tags.
• Exigences d’accès : Déterminez la meilleure approche d’Authentification pour votre base de connaissances.

​

Exportez votre contenu existant

La plupart des plateformes de base de connaissances permettent d’exporter le contenu dans des formats standard. Le format choisi dépend de votre plateforme actuelle et de vos priorités.

• Exportez en Markdown pour une migration simplifiée vers Mintlify. (recommandé)
• Exportez en HTML si le Markdown n’est pas disponible. Vous devrez ensuite convertir votre contenu en Markdown.
• Exportez en JSON ou CSV si vous avez des metadata structurées à préserver.

​

Concevoir la structure de la navigation

Votre structure de navigation détermine comment les utilisateurs accèdent au contenu de votre base de connaissances. Vous pouvez recréer votre structure existante ou la repenser pour mieux correspondre à la façon dont votre équipe conçoit le contenu.

La migration est un bon moment pour améliorer votre structure. Demandez-vous si votre organisation actuelle fonctionne réellement pour votre équipe, ou si vous pouvez la réorganiser pour rendre les informations plus faciles à trouver.

Votre fichier docs.json définit la structure de navigation de votre base de connaissances. Créez ce fichier à la racine de votre référentiel de projet.

{
  "navigation": {
    "groups": [
      {
        "group": "Finance",
        "pages": [
            "finance/overview",
            "finance/budgeting-process",
            "finance/expense-reports",
            "finance/cost-allocation"
        ]
      },
      {
        "group": "HR",
        "pages": [
            "hr/overview",
            "hr/onboarding",
            "hr/benefits",
            "hr/time-off-policy"
        ]
      },
      {
        "group": "Ingénierie",
        "pages": [
          "engineering/overview",
          "engineering/dev-setup",
          "engineering/deployment",
          "engineering/code-standards"
        ]
      }
    ]
  }
}

Consultez la page Navigation pour en savoir plus sur la façon de structurer votre base de connaissances.

​

Configurer l’authentification

Déterminez qui doit avoir accès à quel contenu dans votre base de connaissances.

Si tout le monde doit avoir accès à l’intégralité de la base de connaissances, configurez uniquement l’authentification.

Si vous devez restreindre l’accès à certains contenus à des utilisateurs ou groupes spécifiques, configurez l’authentification avec le contrôle d’accès basé sur les groupes.

​

Migrez votre contenu

Déplacez votre contenu exporté dans une structure de dossiers correspondant à la structure de navigation que vous avez conçue. Convertissez le contenu en Markdown si nécessaire, ajoutez tout frontmatter manquant et configurez les liens internes.

1. Organiser les fichiers

   Créez des dossiers qui correspondent à la structure de votre docs.json. Par exemple, si votre docs.json contient un groupe Finance, créez un dossier finance/ :

   your-project/
   ├── docs.json
   ├── finance/
   │   ├── overview.mdx
   │   ├── budgeting-process.mdx
   │   ├── expense-reports.mdx
   │   └── cost-allocation.mdx
   ├── hr/
   │   ├── overview.mdx
   │   ├── onboarding.mdx
   │   ├── benefits.mdx
   │   └── time-off-policy.mdx
   └── engineering/
       ├── overview.mdx
       ├── dev-setup.mdx
       ├── deployment.mdx
       └── code-standards.mdx
   

   Placez chaque article dans son dossier correspondant. Le chemin doit correspondre au chemin dans votre docs.json. Par exemple, si docs.json fait référence à "finance/expense-reports", le fichier doit être finance/expense-reports.mdx dans votre référentiel de projet.

2. Ajouter un frontmatter à chaque article

   Chaque fichier .mdx a besoin d’un frontmatter en haut avec des métadonnées. Chaque page nécessite un titre et une description. Consultez Pages pour plus d’informations sur les métadonnées de page.

   ---
   title: "Expense Report Process"
   description: "How to submit and track expense reports"
   ---
   
   Votre contenu ici...
   
3. Configurer les liens internes

   Créez des liens entre les pages en utilisant des chemins relatifs à la racine de votre projet.

   Voir le [guide d’onboarding](/hr/onboarding) pour la configuration des nouveaux employés.
   
   Pour toute question, contactez l’[équipe avantages RH](/hr/benefits#common-questions).
   
4. Convertir le HTML et d’autres formats en Markdown

   Si vous avez exporté votre contenu en HTML, convertissez-le en Markdown. Parmi les outils qui peuvent aider :

   • Pandoc : outil en ligne de commande qui convertit entre de nombreux formats.
   • CloudConvert : convertisseur en ligne prenant en charge HTML, DOCX, PDF, et plus encore.
   • Extensions VS Code : recherchez “HTML to Markdown” dans les extensions.
5. Gérer plusieurs formats de contenu

   Si vous avez des PDF, des vidéos ou d’autres médias, décidez comment les inclure dans votre base de connaissances.

   • Intégrer des vidéos : intégrez des vidéos ou créez des liens vers des vidéos hébergées.
   • Lier vers des PDF : ajoutez les PDF à votre référentiel de projet et créez des liens vers eux depuis les pages pertinentes.
   • Convertir des PDF en Markdown : si vous souhaitez que le contenu d’un PDF soit une page, convertissez les PDF en Markdown.

​

Configurer l’Assistant

L’Assistant est automatiquement activé pour les formules Pro et Enterprise. Il permet à votre équipe de poser des questions et d’obtenir des réponses accompagnées de sources citées issues de votre base de connaissances.

Configurez l’Assistant depuis votre dashboard :

• Exemples de questions : Ajoutez des questions fréquentes comme « comment soumettre une note de frais » ou « quelle est la politique de congés » pour que les utilisateurs puissent obtenir des réponses en un clic.
• Sites de recherche : Ajoutez d’autres sites que l’Assistant peut consulter pour répondre aux questions.
• E-mail de secours : Définissez une adresse e-mail de support pour les questions auxquelles l’Assistant ne peut pas répondre.

​

Ajouter l’Assistant à Slack

Le bot Slack permet à votre équipe de poser des questions à l’Assistant directement dans Slack. Créez un canal dans lequel le bot répond à chaque message ou laissez les membres de l’équipe mentionner le bot avec @ dans n’importe quel canal.

​

Activer les contributions de l’équipe

Une base de connaissances reste fiable et à jour lorsque tout le monde peut la modifier, pas seulement les personnes qui l’ont mise en place. Mintlify propose trois moyens pour permettre aux membres de l’équipe de contribuer rapidement à votre base de connaissances.

​

Éditeur web

L’éditeur web permet à chacun de créer et de modifier des pages dans son navigateur. Les contributeurs peuvent :

• Modifier les pages visuellement ou en Markdown.
• Glisser-déposer pour réorganiser la navigation.
• Téléverser des images et des médias.
• Créer des branches et des pull requests (demandes de fusion) pour relecture.

Cela convient bien aux experts métier qui connaissent le contenu mais ne sont pas à l’aise avec les workflows basés sur le code.

​

Agent

L’agent dans votre Dashboard crée des mises à jour de documentation à partir d’instructions en langage naturel. Décrivez ce que vous souhaitez modifier et l’agent crée une pull request (demande de fusion) avec les mises à jour.

Par exemple, un membre de l’équipe pourrait demander « Ajoutez une section à la page de la politique de dépenses expliquant comment soumettre des reçus pour des repas de plus de 50 $ » et copier la page de la politique de dépenses existante dans l’instruction. L’agent rédigerait le contenu et ouvrirait une pull request (demande de fusion) pour relecture.

​

Capturer les connaissances depuis Slack

Les équipes partagent des informations précieuses dans Slack qui ne sont souvent jamais consignées dans la documentation. L’agent dans Slack peut capturer ces connaissances et les convertir en documentation structurée.

Lorsque quelqu’un partage une information utile dans un fil Slack, n’importe quel membre de l’équipe peut mentionner @mintlify avec des instructions pour la documenter. L’agent lit la conversation, extrait les informations pertinentes et crée une pull request (demande de fusion). C’est utile pour capturer des décisions techniques, des solutions de dépannage et des explications de processus tant que le contexte est encore frais.

Par exemple, si votre équipe a discuté dans un fil de la façon de configurer une nouvelle intégration, vous pourriez répondre :

@mintlify Crée un guide pour configurer l’intégration Acme à partir de cette conversation.

L’agent utilise le contexte du fil pour créer une documentation qui capture les informations clés de la discussion.

​

En local

Toute personne ayant accès au référentiel de votre base de connaissances peut travailler en local, dans l’éditeur de son choix, et pousser des modifications sur votre référentiel.

​

Mettre en place des workflows de maintenance

Une base de connaissances peut se dégrader rapidement sans maintenance. Mettez en place des systèmes pour garder le contenu à jour et aider votre équipe à contribuer à la base de connaissances.

1. Attribuer la responsabilité du contenu

   Désignez un responsable ou une petite équipe pour chaque section. Ils n’ont pas besoin d’écrire tout le contenu, mais ils sont chargés de :

   • Examiner le contenu régulièrement.
   • Signaler les informations obsolètes.
   • Approuver les nouvelles pages dans leur section.
   • Répondre lorsque des erreurs sont signalées.
2. Mettre en place des cycles de revue et de vérification du contenu

   Le contenu devient obsolète avec le temps. Établissez un calendrier de revue.

   • Contenu critique : Revue tous les 30 jours
   • Contenu standard : Revue tous les 90 jours
   • Contenu pérenne : Revue annuelle

   Lors de la revue, vérifiez :

   • Les liens sont-ils toujours valides ?
   • Les systèmes ou processus ont-ils changé ?
   • Les exemples sont-ils à jour ?
   • Y a-t-il de nouvelles informations à ajouter ?
3. Créer des directives de contribution

   Facilitez la contribution de chacun à l’amélioration de la base de connaissances. Vos directives doivent couvrir :

   • Format : Avez-vous des modèles spécifiques ou des exigences de format ?
   • Processus : Comment quelqu’un doit-il proposer et soumettre des modifications ?
   • Revue : Qui examine les propositions ? Quel est le délai de traitement ?
   • Périmètre : Quels types de contenu sont concernés ?
4. Suivre les indicateurs d'utilisation

   Analysez comment votre équipe utilise la base de connaissances pour prioriser le contenu et identifier les axes d’amélioration. Définissez une fréquence régulière pour l’examen des indicateurs d’utilisation — mensuel ou trimestriel sont de bons intervalles.

   • Quels articles obtiennent le plus de consultations ? Assurez-vous qu’ils restent exacts et faciles à lire.
   • Quels articles n’ont aucune consultation ? Envisagez de les supprimer ou d’améliorer leur découvrabilité.
   • Quel est le taux de rebond ? Si les personnes quittent la page immédiatement, le contenu n’est peut-être pas utile ou la navigation pourrait être améliorée.

​

Prochaines étapes

Votre base de connaissances est prête à être lancée. Après le déploiement :

1. Présentez la base de connaissances à votre équipe.
2. Surveillez l’utilisation et les tendances de recherche dans vos Analytics.
3. Encouragez les contributions lorsque des lacunes sont identifiées.
4. Révisez et mettez à jour le contenu régulièrement.

Les bases de connaissances les plus efficaces évoluent en fonction de la manière dont les équipes les utilisent réellement.