Rédiger avec l'IA

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, Cursor ou 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.

Write docs for the webhook feature.

Document authentication.

Create a getting started guide.

Ces prompts produisent une sortie générique et volumineuse, car l'IA n'a aucune contrainte.

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

Erreurs courantes de l'IA

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

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.

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.

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.

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.

« 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. »

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.

Après avoir livré une fonctionnalité, soumettez ce prompt à votre outil d'IA :

I just added [feature]. Update the docs to reflect this change.
Reference the implementation in /src/[file] for accuracy.

Squelette de page

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

---
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 ?

Mises à jour automatisées

Exécutez /update-jamdesk pour générer de la documentation à partir des modifications de code

Composants MDX

Référence complète des composants disponibles