Back to Details

docs-write

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Writing Skill

文档编写技能

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

When writing documentation

编写文档时的注意事项

Start here

入门要点

  1. Who is this for? Match complexity to audience. Don't oversimplify hard things or overcomplicate simple ones.
  2. What do they need? Get them to the answer fast. Nobody wants to be in docs longer than necessary.
  3. What did you struggle with? Those common questions you had when learning? Answer them (without literally including the question).
  1. 这份文档面向谁？ 根据受众匹配内容复杂度。不要过度简化复杂内容，也不要把简单内容复杂化。
  2. 他们需要什么？ 让读者快速找到答案。没人想在文档里花费不必要的时间。
  3. 你学习时遇到过哪些困难？ 把你学习过程中遇到的常见问题解答出来（无需直接列出问题）。

Writing process

写作流程

Draft:
  • Write out the steps/explanation as you'd tell a colleague
  • Lead with what to do, then explain why
  • Use headings that state your point: "Set SAML before adding users" not "SAML configuration timing"
Edit:
  • Read aloud. Does it sound like you talking? If it's too formal, simplify.
  • Cut anything that doesn't directly help the reader
  • Check each paragraph has one clear purpose
  • Verify examples actually work (don't give examples that error)
Polish:
  • Make links descriptive (never "here")
  • Backticks only for code/variables, bold for UI elements
  • American spelling, serial commas
  • Keep images minimal and scoped tight
Format:
  • Run prettier on the file after making edits: 
    yarn prettier --write <file-path>
  • This ensures consistent formatting across all documentation
草稿阶段：
  • 像给同事讲解一样写出步骤/说明
  • 先讲怎么做，再解释原因
  • 使用明确表达核心内容的标题：比如“添加用户前先配置SAML”，而非“SAML配置时机”
编辑阶段：
  • 大声朗读。听起来像你在说话吗？如果过于正式，就简化语言。
  • 删除所有对读者没有直接帮助的内容
  • 确保每个段落只有一个明确的核心
  • 验证示例确实可用（不要提供会报错的示例）
润色阶段：
  • 使用描述性链接（绝对不要用“这里”）
  • 仅对代码/变量使用反引号，对UI元素使用粗体
  • 使用美式拼写，添加牛津逗号
  • 尽量少用图片，且图片要聚焦核心内容
格式规范：
  • 编辑完成后对文件运行prettier：
    yarn prettier --write <file-path>
  • 这能确保所有文档的格式保持一致

Common patterns

常见模式

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

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

This ensures you're getting the latest changes.
Not: "(remember to run X before Y...)" buried in a paragraph.
Headings:
  • "Use environment variables for configuration" ✅
  • "Environment variables" ❌ (too vague)
  • "How to use environment variables for configuration" ❌ (too wordy)
Links:
  • "Check out the SAML documentation" ✅
  • "Read the docs here" ❌
操作说明：
markdown
Run:
\`\`\`
command-to-run
\`\`\`

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

This ensures you're getting the latest changes.
不要：把“（记得在Y之前运行X...）”这类内容埋在段落里。
标题：
  • “使用环境变量进行配置” ✅
  • “环境变量” ❌（过于模糊）
  • “如何使用环境变量进行配置” ❌（过于冗长）
链接：
  • “查看SAML文档” ✅
  • “点击这里阅读文档” ❌

Watch out for

需要注意的问题

  • Describing tasks as "easy" (you don't know the reader's context)
  • Using "we" when talking about Metabase features (use "Metabase" or "it")
  • Formal language: "utilize", "reference", "offerings"
  • Too peppy: multiple exclamation points
  • Burying the action in explanation
  • Code examples that don't work
  • Numbers that will become outdated
  • 不要将任务描述为“简单”（你不了解读者的背景）
  • 谈论Metabase功能时不要用“我们”，要用“Metabase”或“它”
  • 避免使用正式术语：比如“utilize”（使用）、“reference”（查看）、“offerings”（产品）
  • 不要过于活泼：避免多个感叹号
  • 不要把操作步骤埋在说明文字里
  • 不要提供无法运行的代码示例
  • 不要使用容易过时的数字

Quick reference

快速参考

Write ThisNot This
people, companiesusers
summarizeaggregate
take a look atreference
can't, don'tcannot, do not
Filter button`Filter` button
Check out the docsClick here
推荐写法避免写法
people, companiesusers
summarizeaggregate
take a look atreference
can't, don'tcannot, do not
Filter按钮`Filter`按钮
查看文档点击这里