Writing with AI
Practical strategies for writing Jamdesk documentation with AI tools. Covers effective prompts, review checklists, and common pitfalls.
These strategies work regardless of which AI tool you use — Claude Code, Cursor, Codex, Copilot, or anything else. For tool-specific setup, see Claude Code, Cursor, or Codex.
Why MDX Works Well with AI
MDX is one of the easiest formats for AI tools to work with:
- Familiar syntax — AI models are trained on millions of Markdown files, so they produce valid MDX with minimal prompting
- Structured components —
<Card>,<Steps>,<Tabs>have predictable patterns that models learn quickly - Plain text — No binary formats, no proprietary schemas, no build artifacts to interpret
Write Better Prompts
The difference between mediocre AI docs and good ones is usually the prompt. Be specific about what you want.
Write docs for the webhook feature.
Document authentication.
Create a getting started guide.
These produce generic, bloated output because the AI has no constraints.
Prompting Patterns That Work
| Pattern | Example |
|---|---|
| Specify the reader | "The reader is a backend developer who has never used our API" |
| Name the structure | "Use Steps for the setup flow, then Tabs for language variants" |
| Set length limits | "Keep the intro under 2 sentences" or "Each accordion answer should be 3-4 lines" |
| Point to source code | "Reference the implementation in /src/auth for accuracy" |
| Say what to skip | "Don't explain what REST is. Skip the theory." |
| Give an example page | "Match the tone and structure of /quickstart" |
Review AI Output
AI tools produce structurally correct MDX most of the time. The problems are subtler — tone, accuracy, and bloat. Run through this checklist before committing.
Voice Check
Read the output out loud. If it sounds like a chatbot, rewrite it. Watch for:
- Filler phrases — "It's important to note that", "This allows you to", "In order to"
- Hedging — "You might want to consider", "It's generally recommended"
- Empty transitions — "Now that we've covered X, let's move on to Y"
- Buzzwords — "seamlessly", "robust", "leverage", "streamline"
Cut these. The page will be shorter and better.
Accuracy Check
AI tools confidently produce wrong information. Verify:
- Do the code examples actually work? Copy-paste and run them.
- Are config options real? Check against source code.
- Are component names correct? Only use components that exist.
- Does the page describe current behavior, not aspirational features?
Structure Check
- Frontmatter has both
titleanddescription - Opening paragraph exists with no heading before it
- Page ends with "What's Next?" cards in a
<Columns>wrapper - New pages are added to
docs.jsonnavigation - No invented components — only the ones in the component reference
Common AI Mistakes
These show up often enough to watch for:
AI tools generate <CodeBlock>, <Alert>, <Section>, <Callout>, and other components that don't exist in Jamdesk. Stick to the components listed in the overview.
Creating a page without adding it to docs.json is the most common mistake. The page will exist but won't appear in the sidebar. Always update navigation when creating pages.
AI tools love wrapping every other paragraph in a <Note> or <Warning>. One or two callouts per page is plenty. If everything is important, nothing is.
A 200-line page from AI usually has 100 lines of actual content. Look for repeated explanations, unnecessary background, and paragraphs that say the same thing in different words. Cut aggressively.
"This powerful feature allows you to..." tells the reader nothing. Replace with what it actually does: "Send HTTP POST requests to your endpoint when events fire."
Keep Docs in Sync
The hard part isn't writing docs — it's keeping them current when code changes.
After shipping a feature, prompt your AI tool:
I just added [feature]. Update the docs to reflect this change.
Reference the implementation in /src/[file] for accuracy.
Page Skeleton
Use this as a starting prompt when asking AI to create a new page:
---
title: Feature Name
description: One sentence — 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>