docs-write

文档写作技能

@./../_shared/metabase-style-guide.md

撰写文档时

从这里开始

1. 这是写给谁的？ 让复杂程度与受众匹配。不要把难的事情过度简化，也不要把简单的事情复杂化。
2. 他们需要什么？ 让他们快速找到答案。没人愿意在文档里待得比必要的时间更久。
3. 你当初卡在哪里？ 你学习时遇到的那些常见问题？回答它们（但不要把问题原样写进去）。

写作流程

草稿：

• 像对同事讲述那样把步骤/说明写出来
• 先说要做什么，再解释为什么
• 用能表明观点的标题："Set SAML before adding users" 而不是 "SAML configuration timing"

编辑：

• 大声读出来。听起来像你在说话吗？如果太正式，就简化。
• 删掉任何不能直接帮助读者的内容
• 检查每个段落都有一个明确的目的
• 验证示例确实可用（不要给出会报错的示例）

润色：

• 让链接具有描述性（绝不用 "here"）
• 反引号只用于代码/变量，粗体用于 UI 元素
• 美式拼写，序列逗号
• 保持图片精简且范围紧凑

格式：

• 编辑后对文件运行 prettier：bun run prettier --write <file-path>
• 这能确保所有文档格式一致

常见模式

说明：

Run:
\`\`\`
command-to-run
\`\`\`

Then:
\`\`\`
next-command
\`\`\`

This ensures you're getting the latest changes.

而不是：把 "(remember to run X before Y...)" 埋在段落里。

标题：

• "Use environment variables for configuration" ✅
• "Environment variables" ❌（太含糊）
• "How to use environment variables for configuration" ❌（太啰嗦）

链接：

• "Check out the SAML documentation" ✅
• "Read the docs here" ❌

注意避免

• 把任务描述为 "easy"（你不了解读者的背景）
• 在谈论 Metabase 功能时使用 "we"（要用 "Metabase" 或 "it"）
• 正式用语："utilize"、"reference"、"offerings"
• 过于亢奋：多个感叹号
• 把操作埋在解释里
• 不能用的代码示例
• 会过时的数字

快速参考

这样写	不要这样写
people, companies	users
summarize	aggregate
take a look at	reference
can't, don't	cannot, do not
Filter button	`Filter` button
Check out the docs	Click here