---
title: Rédiger avec l'IA
description: Stratégies pratiques pour rédiger la documentation Jamdesk avec l'IA. Prompts efficaces, listes de vérification et erreurs courantes à éviter.
---

Ces stratégies fonctionnent quel que soit l'outil d'IA utilisé : Claude Code, Cursor, Codex, Copilot ou tout autre. Pour la configuration propre à chaque outil, consultez [Claude Code](/fr/ai/claude-code), [Cursor](/fr/ai/cursor) ou [Codex](/fr/ai/codex).

## Pourquoi MDX fonctionne bien avec l'IA

MDX est l'un des formats les plus faciles à utiliser pour les outils d'IA :

- Syntaxe familière : les modèles d'IA sont entraînés sur des millions de fichiers Markdown, ils produisent donc du MDX valide avec un minimum de prompting.
- Composants structurés : `<Card>`, `<Steps>` et `<Tabs>` ont des patterns prévisibles que les modèles apprennent rapidement.
- Texte brut : MDX ne comporte ni formats binaires, ni schémas propriétaires, ni artefacts de build qu'un outil d'IA devrait interpréter.

## Écrire de meilleurs prompts

La différence entre une documentation IA médiocre et une bonne documentation tient généralement au prompt. Soyez précis sur ce que vous attendez.

<Tabs>
  <Tab title="Prompts faibles">
    ```text
    Write docs for the webhook feature.
    ```

    ```text
    Document authentication.
    ```

    ```text
    Create a getting started guide.
    ```

    Ces prompts produisent une sortie générique et volumineuse, car l'IA n'a aucune contrainte.
  </Tab>
  <Tab title="Prompts forts">
    ```text
    Write a page documenting our webhook feature. The reader is a developer
    integrating webhooks for the first time. Start with a 3-step quickstart,
    then cover payload format and retry behavior. Reference /src/webhooks
    for the implementation.
    ```

    ```text
    Add a troubleshooting section to the authentication page. Cover these
    three errors: expired tokens, missing scopes, and rate limits. Use
    Accordions for each error. Keep each answer under 4 lines.
    ```

    ```text
    Create a getting started guide that gets the reader from zero to a
    working hello-world in under 2 minutes. Skip the theory and background,
    and jump straight into the install command.
    ```

    Les contraintes produisent une sortie ciblée. Indiquez à l'IA qui est le lecteur, quelle structure utiliser et ce qu'il faut omettre.
  </Tab>
</Tabs>

### Patterns de prompting efficaces

| Pattern | Exemple |
|---------|---------|
| **Préciser le lecteur** | « Le lecteur est un développeur backend qui n'a jamais utilisé notre API » |
| **Nommer la structure** | « Utilise Steps pour le flux de configuration, puis Tabs pour les variantes de langage » |
| **Fixer des limites de longueur** | « L'intro doit tenir en moins de 2 phrases » ou « Chaque réponse d'accordion doit faire 3-4 lignes » |
| **Pointer vers le code source** | « Référence l'implémentation dans /src/auth pour être précis » |
| **Dire ce qu'il faut omettre** | « N'explique pas ce qu'est REST. Passe la théorie. » |
| **Donner une page exemple** | « Adopte le ton et la structure de /quickstart » |

## Relire la sortie de l'IA

Les outils d'IA produisent du MDX structurellement correct la plupart du temps. Les problèmes plus subtils concernent le ton, la précision et le superflu. Parcourez cette liste de vérification avant de valider.

### Vérification du style

Lisez la sortie à voix haute. Si cela ressemble à un chatbot, réécrivez. Faites attention à :

- Les formules creuses : « It's important to note that », « This allows you to », « In order to »
- Les formules hésitantes : « You might want to consider », « It's generally recommended »
- Les transitions vides : « Now that we've covered X, let's move on to Y »
- Les buzzwords : « seamlessly », « robust », « leverage », « streamline »

Supprimez-les. La page sera plus courte et meilleure.

### Vérification de l'exactitude

Les outils d'IA produisent des informations erronées avec assurance. Vérifiez :

- Les exemples de code fonctionnent-ils réellement ? Copiez-collez et exécutez-les.
- Les options de configuration existent-elles ? Vérifiez dans le code source.
- Les noms de composants sont-ils corrects ? Utilisez uniquement les [composants qui existent](/fr/components/overview).
- La page décrit-elle le comportement actuel et non des fonctionnalités à venir ?

### Vérification de la structure

- [ ] Le frontmatter contient bien `title` et `description`
- [ ] Un paragraphe d'ouverture existe, sans titre avant lui
- [ ] La page se termine par des cards « Et ensuite ? » dans un wrapper `<Columns>`
- [ ] Les nouvelles pages sont ajoutées à la navigation dans `docs.json`
- [ ] Aucun composant inventé ; seulement ceux listés dans la [référence des composants](/fr/components/overview)

## Erreurs courantes de l'IA

Ces erreurs reviennent assez souvent pour mériter d'y être attentif :

<AccordionGroup>
  <Accordion title="Inventer des composants qui n'existent pas">
    Les outils d'IA génèrent `<CodeBlock>`, `<Alert>`, `<Section>`, `<Callout>` et d'autres composants qui n'existent pas dans Jamdesk. Tenez-vous aux composants listés dans l'[aperçu](/fr/components/overview).
  </Accordion>
  <Accordion title="Oublier la navigation dans docs.json">
    Créer une page sans l'ajouter à `docs.json` est l'erreur la plus fréquente. La page existera mais n'apparaîtra pas dans la barre latérale. Mettez toujours à jour la navigation lors de la création de pages.
  </Accordion>
  <Accordion title="Abuser des callouts">
    Les outils d'IA adorent entourer chaque autre paragraphe d'un `<Note>` ou d'un `<Warning>`. Un ou deux callouts par page suffisent. Si tout est important, rien ne l'est.
  </Accordion>
  <Accordion title="Écrire trop">
    Une page de 200 lignes générée par l'IA contient généralement 100 lignes de contenu réel. Repérez les explications répétées, les arrière-plans inutiles et les paragraphes qui disent la même chose avec des mots différents. Coupez sans hésiter.
  </Accordion>
  <Accordion title="Descriptions génériques">
    « This powerful feature allows you to... » ne dit rien au lecteur. Remplacez par ce que ça fait concrètement : « Send HTTP POST requests to your endpoint when events fire. »
  </Accordion>
</AccordionGroup>

## Maintenir la documentation à jour

La partie difficile n'est pas de rédiger la documentation. C'est de la maintenir à jour lorsque le code évolue.

<Tabs>
  <Tab title="Prompting manuel">
    Après avoir livré une fonctionnalité, soumettez ce prompt à votre outil d'IA :

    ```text
    I just added [feature]. Update the docs to reflect this change.
    Reference the implementation in /src/[file] for accuracy.
    ```
  </Tab>
  <Tab title="Automatisé avec /update-jamdesk">
    La compétence `/update-jamdesk` pour Claude Code analyse vos modifications de code et génère les mises à jour de documentation correspondantes. Exécutez-la après avoir implémenté des fonctionnalités visibles par l'utilisateur :

    ```text
    /update-jamdesk
    ```

    Consultez [Mises à jour automatisées](/fr/ai/automated-updates) pour la configuration complète.
  </Tab>
</Tabs>

## Squelette de page

Utilisez ceci comme prompt de départ pour demander à l'IA de créer une nouvelle page :

```mdx
---
title: Feature Name
description: One sentence summarizing what this page covers.
---

Opening paragraph: what problem this solves and who should read this.

## Quick Start

<Steps>
  <Step title="First step">What to do.</Step>
  <Step title="Second step">What to do next.</Step>
</Steps>

## How It Works

Explain the mechanics. Use code examples.

## What's Next?

<Columns cols={2}>
  <Card title="Related Page" icon="arrow-right" href="/path">
    Why the reader would go here next
  </Card>
</Columns>
```

## Et ensuite ?

<Columns cols={2}>
  <Card title="Mises à jour automatisées" icon="rotate" href="/fr/ai/automated-updates">
    Exécutez `/update-jamdesk` pour générer de la documentation à partir des modifications de code
  </Card>
  <Card title="Composants MDX" icon="puzzle-piece" href="/fr/components/overview">
    Référence complète des composants disponibles
  </Card>
</Columns>