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.

​

Introduction

Ce guide vous explique comment créer une base de connaissances interne sur Mintlify. Vous allez configurer une structure de navigation, migrer du contenu, configurer l’authentification et mettre en place un processus de maintenance.

Ce guide part du principe que vous migrez du contenu depuis une base de connaissances existante vers Mintlify. Si vous créez une base de connaissances avec un contenu entièrement nouveau, vous pouvez suivre des étapes similaires, mais ignorer l’audit et les étapes de migration.

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

​

Prérequis

• 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

​

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 qui doit être conservée, 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 façon dont votre base de connaissances est organisée. 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": "RH",
        "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 et la personnalisation.

​

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 du fichier 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.

​

Optimiser la visibilité

​

Configurer l’Assistant IA

L’Assistant est automatiquement activé pour les formules Pro et Custom. Vous pouvez personnaliser l’assistant depuis votre Dashboard.

• Sites de recherche : Sélectionnez des sites supplémentaires, en plus de votre base de connaissances, que l’assistant peut consulter lorsqu’il répond aux questions.
• Définir des exemples de questions : Définissez les questions par défaut qui s’affichent lorsque quelqu’un ouvre le panneau de l’assistant. Si les utilisateurs posent souvent des questions comme « comment soumettre un rapport de frais » ou « quelle est la politique de congés de l’entreprise », ajoutez-les ici pour leur faire gagner du temps.

​

Intégration Slack

Si votre équipe utilise Slack, vous pouvez ajouter l’application Slack à votre espace de travail. Cela permet à votre équipe d’interroger votre base de connaissances sans quitter Slack.

​

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.