Rédiger avec l'IA
Stratégies pratiques pour rédiger la documentation Jamdesk avec des outils d'IA : prompts efficaces, listes de contrôle et pièges courants.
Ces stratégies fonctionnent quel que soit l'outil d'IA que vous utilisez : Claude Code, Cursor, Codex, Copilot, ou tout autre. Pour la configuration spécifique à 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 prompts.
- Composants structurés :
<Card>,<Steps>et<Tabs>suivent des schémas prévisibles que les modèles apprennent rapidement. - Texte brut : MDX ne contient ni formats binaires, ni schémas propriétaires, ni artefacts de build qu'un outil d'IA doive interpréter.
Rédiger 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 voulez.
Write docs for the webhook feature.Document authentication.Create a getting started guide.Cela produit un résultat générique et surchargé, car l'IA n'a aucune contrainte.
Modèles de prompts efficaces
| Modèle | Exemple |
|---|---|
| Préciser le lecteur | "Le lecteur est un développeur backend qui n'a jamais utilisé notre API" |
| Nommer la structure | "Utilisez Steps pour le flux de configuration, puis Tabs pour les variantes de langage" |
| Définir des limites de longueur | "Gardez l'intro en moins de 2 phrases" ou "Chaque réponse d'accordéon doit faire 3 à 4 lignes" |
| Indiquer le code source | "Référencez l'implémentation dans /src/auth pour plus de précision" |
| Indiquer ce qu'il faut omettre | "N'expliquez pas ce qu'est REST. Passez la théorie." |
| Donner une page d'exemple | "Respectez le ton et la structure de /quickstart" |
Réviser le résultat de l'IA
Les outils d'IA produisent la plupart du temps du MDX structurellement correct. Les problèmes les plus subtils concernent le ton, la précision et la verbosité. Parcourez cette liste de contrôle avant de valider.
Vérification du ton
Lisez le résultat à voix haute. S'il sonne comme un chatbot, réécrivez-le. Surveillez :
- Expressions creuses : "Il est important de noter que", "Cela vous permet de", "Afin de"
- Atténuations : "Vous pourriez envisager de", "Il est généralement recommandé de"
- Transitions vides : "Maintenant que nous avons couvert X, passons à Y"
- Mots à la mode : "en toute transparence", "robuste", "exploiter", "rationaliser"
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-les et exécutez-les.
- Les options de configuration existent-elles réellement ? Vérifiez-les dans le code source.
- Les noms des composants sont-ils corrects ? N'utilisez que des composants qui existent.
- La page décrit-elle le comportement actuel, et non des fonctionnalités envisagées ?
Vérification de la structure
- Le frontmatter contient à la fois
titleetdescription - Un paragraphe d'introduction existe avant tout titre
- La page se termine par des cartes "Et ensuite ?" dans un wrapper
<Columns> - Les nouvelles pages sont ajoutées à la navigation
docs.json - Aucun composant inventé ; utilisez uniquement ceux de la référence des composants
Erreurs courantes de l'IA
Elles reviennent assez souvent pour qu'on y prête attention :
Les outils d'IA génèrent <CodeBlock>, <Alert>, <Section>, <Callout> et d'autres composants qui n'existent pas dans Jamdesk. Limitez-vous aux composants listés dans l'aperçu.
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 entourer un paragraphe sur deux d'un <Note> ou d'un <Warning>. Un ou deux encadrés par page suffisent largement. Si tout est important, rien ne l'est.
Une page de 200 lignes générée par l'IA ne contient généralement que 100 lignes de contenu réel. Repérez les explications répétées, le contexte superflu et les paragraphes qui disent la même chose avec d'autres mots. Coupez sans hésiter.
"Cette fonctionnalité puissante vous permet de..." ne dit rien au lecteur. Remplacez par ce qu'elle fait réellement : "Envoie des requêtes HTTP POST à votre endpoint lorsque des événements se déclenchent."
Garder la documentation synchronisée
Rédiger la documentation est la partie facile. La maintenir à jour quand le code change est plus difficile.
Après avoir déployé une fonctionnalité, donnez 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 lorsque vous demandez à l'IA de créer une nouvelle page :
Créer une page de documentation Jamdesk
La carte ci-dessus copie les instructions complètes et le squelette. Son code source utilise la même syntaxe de composant que vous pouvez ajouter à vos propres pages :
<Prompt title="Create a Jamdesk documentation page" actions={["cursor", "claude", "chatgpt"]}>
Create a Jamdesk documentation page using this structure. Replace each
placeholder with specific, accurate content for the feature I describe.
```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>
```
</Prompt>