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 spécifique à chaque outil, voir 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 : pas de formats binaires, pas de schémas propriétaires, pas d'artefacts de build à interpréter.

Écrire de meilleurs prompts

La différence entre une documentation IA médiocre et une bonne documentation réside généralement dans le prompt. Soyez précis sur ce que vous voulez.

Write docs for the webhook feature.

Document authentication.

Create a getting started guide.

Ces prompts produisent un résultat générique et superflu car l'IA n'a pas de contraintes.

Patterns de prompting efficaces

Pattern	Exemple
Préciser le lecteur	"The reader is a backend developer who has never used our API"
Nommer la structure	"Use Steps for the setup flow, then Tabs for language variants"
Définir des limites de longueur	"Keep the intro under 2 sentences" ou "Each accordion answer should be 3-4 lines"
Pointer vers le code source	"Reference the implementation in /src/auth for accuracy"
Dire ce qu'il faut omettre	"Don't explain what REST is. Skip the theory."
Donner une page d'exemple	"Match the tone and structure of /quickstart"

Réviser le résultat de l'IA

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

Vérification du ton

Lisez le résultat à voix haute. Si ça ressemble à un chatbot, réécrivez. Surveillez :

Les phrases de remplissage : "It's important to note that", "This allows you to", "In order to"
Les formulations évasives : "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 mots à la mode : "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-les et exécutez-les.
Les options de configuration sont-elles réelles ? Vérifiez dans le code source.
Les noms des composants sont-ils corrects ? N'utilisez que les composants qui existent.
La page décrit-elle le comportement actuel, et non des fonctionnalités aspirationnelles ?

Vérification de la structure

Le frontmatter contient title et description
Le paragraphe d'introduction existe sans titre avant lui
La page se termine par des cartes "What's Next?" dans un wrapper <Columns>
Les nouvelles pages sont ajoutées à la navigation docs.json
Aucun composant inventé ; uniquement ceux de la référence des composants

Erreurs courantes de l'IA

Ces erreurs apparaissent assez souvent pour mériter attention :

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

Créer une page sans l'ajouter à docs.json est l'erreur la plus courante. 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 encadrer chaque second paragraphe dans une <Note> ou 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 IA contient généralement 100 lignes de contenu réel. Cherchez les explications répétées, le contexte inutile 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 réellement : "Send HTTP POST requests to your endpoint when events fire."

Maintenir la documentation à jour

La partie difficile n'est pas d'écrire la documentation. C'est de la maintenir à jour lorsque le code change.

Après avoir livré une fonctionnalité, utilisez ce prompt avec 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 lorsque vous demandez à 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 changements de code

Composants MDX

Référence complète des composants disponibles