Créer une documentation développeur

La documentation développeur aide les développeurs à comprendre votre produit et à s’y intégrer. Une bonne documentation permet aux développeurs de faire plus avec votre produit, réduit la charge du support, accélère l’adoption et améliore l’expérience développeur.

Mintlify fournit une infrastructure conçue pour la documentation développeur.

• Génération de références d’API : générez des références d’API interactives à partir de spécifications OpenAPI qui permettent aux développeurs de tester des endpoints directement dans votre documentation.
• Blocs de code avec explications : l’Assistant explique les exemples de code dans leur contexte, aidant les développeurs à comprendre les détails d’implémentation.
• Synchronisation Git : gardez la documentation synchronisée avec votre base de code en utilisant GitHub ou GitLab.
• Gestion des versions : maintenez la documentation pour plusieurs versions afin que les développeurs sur d’anciennes versions puissent toujours trouver des informations précises.

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

• Votre spécification d’API au format OpenAPI (si vous documentez une API)
• Un référentiel Git pour votre documentation
• Un accès administrateur à votre organisation Mintlify

Si vous créez une nouvelle documentation à partir de zéro, passez à la section Planifier la structure de votre documentation.

Passez en revue votre documentation actuelle pour comprendre ce que vous avez déjà et ce que vous devez migrer.

• Référence d’API : Est-elle générée à partir d’une spécification ou rédigée manuellement ? Quels endpoints documentez-vous ?
• Guides et tutoriels : Quels guides d’intégration existent ? Sont-ils à jour ?
• Exemples de code : Quels langages et frameworks utilisez-vous ?
• Documentation SDK : Avez-vous une documentation distincte pour chaque SDK ?
• Journal des modifications : Tenez-vous un journal des modifications ou des notes de version ?
• Metadata : Disposez-vous de metadata pour votre contenu, comme des dates, des auteurs et des tags ?

• Exportez en Markdown pour une migration simplifiée vers Mintlify.
• Exportez les spécifications OpenAPI pour la documentation de référence de votre API.
• Exportez en HTML si Markdown n’est pas disponible, puis convertissez-le en Markdown.

La documentation pour développeurs inclut généralement plusieurs types de contenus. Structurez votre navigation en fonction de la façon dont vos utilisateurs comprennent votre produit.

{
  "navigation": {
    "groups": [
      {
        "group": "Get Started",
        "pages": [
          "introduction",
          "quickstart",
          "authentication"
        ]
      },
      {
        "group": "Guides",
        "pages": [
          "guides/webhooks",
          "guides/error-handling",
          "guides/rate-limits",
          "guides/pagination"
        ]
      },
      {
        "group": "Référence API",
        "pages": [
          "api-reference/overview",
          "api-reference/users",
          "api-reference/orders",
          "api-reference/products"
        ]
      },
      {
        "group": "SDKs",
        "pages": [
          "sdks/javascript",
          "sdks/python",
          "sdks/go"
        ]
      }
    ]
  }
}

Pour davantage d’options de configuration, voir Navigation.

Si vous avez une API, générez une référence interactive à partir de votre spécification OpenAPI.

your-project/
├── docs.json
├── openapi.yaml
└── api-reference/
    └── overview.mdx

{
  "openapi": "openapi.yaml"
}

{
  "group": "Référence API",
  "pages": [
    "api-reference/overview",
    "api-reference/users/list-users",
    "api-reference/users/get-user",
    "api-reference/users/create-user"
  ]
}

L’Assistant aide les développeurs à trouver des réponses et à comprendre les exemples de code. Configurez-le depuis votre dashboard.

• Exemples de questions : Ajoutez des questions à destination des développeurs comme « Comment authentifier des requêtes API ? » ou « Montre-moi comment gérer les webhooks. »
• Explications de code : L’Assistant peut expliquer des code blocks dans leur contexte lorsque les développeurs posent des questions sur des exemples spécifiques.

Si vous maintenez plusieurs versions d’API, configurez la gestion des versions afin que les développeurs puissent trouver la documentation de leur version.

{
  "versions": ["v2", "v1"],
  "navigation": {
    "groups": [
      {
        "group": "Référence de l'API",
        "version": "v2",
        "pages": ["v2/api-reference/users"]
      },
      {
        "group": "Référence de l'API",
        "version": "v1",
        "pages": ["v1/api-reference/users"]
      }
    ]
  }
}

Pour en savoir plus, consultez Versions.

Installez la GitHub App Mintlify pour garder la documentation synchronisée avec votre base de code et faciliter les contributions.

La documentation développeur nécessite des mises à jour régulières afin que les informations restent exactes et utilisables.

Votre documentation pour développeurs est prête à être lancée. Après le déploiement :

1. Annoncez la mise en ligne de la documentation à votre communauté de développeurs.
2. Surveillez les tendances de recherche et les conversations de l’Assistant pour identifier les lacunes.
3. Mettez en place un processus pour mettre à jour la documentation à chaque nouvelle version de l’API.
4. Recueillez les retours des développeurs pour améliorer le contenu au fil du temps.