使用 AI 写作
介绍使用 AI 工具编写 Jamdesk 文档的实用策略，包括有效提示词、审核清单和常见问题。
无论使用哪种 AI 工具，这些策略都适用：Claude Code、Cursor、Codex、Copilot 或其他工具。如需了解特定工具的设置，请参阅 Claude Code、Cursor 或 Codex。
MDX 为什么适合 AI
MDX 是最容易供 AI 工具处理的格式之一：
- 语法熟悉：AI 模型基于数百万个 Markdown 文件进行训练，因此只需很少的提示词就能生成有效的 MDX。
- 组件结构化：
<Card>、<Steps>和<Tabs>具有模型可以快速学习的固定模式。 - 纯文本：MDX 不包含 AI 工具需要解释的二进制格式、专有架构或构建产物。
编写更好的提示词
普通 AI 文档与优秀 AI 文档之间的差异通常在于提示词。请明确说明你的需求。
Write docs for the webhook feature.Document authentication.Create a getting started guide.这些提示词没有任何约束，因此生成的内容通常泛泛而谈且过于冗长。
有效的提示词模式
| 模式 | 示例 |
|---|---|
| 明确读者 | "The reader is a backend developer who has never used our API" |
| 指定结构 | "Use Steps for the setup flow, then Tabs for language variants" |
| 设置长度限制 | "Keep the intro under 2 sentences" or "Each accordion answer should be 3-4 lines" |
| 指向源代码 | "Reference the implementation in /src/auth for accuracy" |
| 说明要跳过的内容 | "Don't explain what REST is. Skip the theory." |
| 提供示例页面 | "Match the tone and structure of /quickstart" |
审核 AI 输出
AI 工具大多数时候都能生成结构正确的 MDX。更隐蔽的问题通常在于语气、准确性和内容冗余。提交前，请使用以下清单进行检查。
语气检查
大声读出生成的内容。如果听起来像聊天机器人，请重写。注意以下问题：
- 填充语句："It's important to note that"、"This allows you to"、"In order to"
- 模棱两可："You might want to consider"、"It's generally recommended"
- 空洞的过渡："Now that we've covered X, let's move on to Y"
- 流行术语："seamlessly"、"robust"、"leverage"、"streamline"
删除这些内容。页面会更简洁，也更好。
准确性检查
AI 工具会自信地生成错误信息。请验证：
- 代码示例是否确实可运行？复制粘贴后执行。
- 配置选项是否真实存在？对照源代码检查。
- 组件名称是否正确？只能使用现有组件。
- 页面描述的是当前行为，而不是设想中的功能吗？
结构检查
- Frontmatter 同时包含
title和description - 存在开头段落，且此前没有标题
- 页面以
<Columns>包裹的 "What's Next?" 卡片结尾 - 新页面已添加到
docs.json导航 - 没有虚构组件；只能使用组件参考中的组件
常见 AI 错误
以下问题出现得足够频繁，值得特别注意：
AI 工具会生成 Jamdesk 中不存在的 <CodeBlock>、<Alert>、<Section>、<Callout> 及其他组件。请仅使用概览中列出的组件。
创建页面时不将其添加到 docs.json 是最常见的错误。页面虽然存在，但不会显示在侧边栏中。创建页面时，请始终更新导航。
AI 工具喜欢将每个段落都包裹在 <Note> 或 <Warning> 中。每页使用一两个提示框就足够了。如果所有内容都很重要，就等于没有重点。
AI 生成的 200 行页面通常只有 100 行是真正的内容。查找重复说明、不必要的背景介绍，以及用不同措辞表达相同内容的段落。大胆删减。
"This powerful feature allows you to..." 什么也没有告诉读者。请改为说明它实际执行的操作："Send HTTP POST requests to your endpoint when events fire."
保持文档同步
编写文档很容易。代码发生变化后让文档保持最新则更难。
发布功能后，向 AI 工具发送提示词：
I just added [feature]. Update the docs to reflect this change.
Reference the implementation in /src/[file] for accuracy.页面骨架
请求 AI 创建新页面时，可以将以下内容作为起始提示词：
创建 Jamdesk 文档页面
上方的实时卡片复制了完整的说明和骨架。其源代码使用了与你可以添加到自己页面中的相同组件语法：
<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>