用途:在创建或编辑文档文件(Markdown、MDX 等)时,按 Metabase 的对话式、清晰、面向用户的风格撰写文档。
主要能力与写作要点:先明确读者是谁、需要什么、学习时常见的困惑,并据此匹配复杂度;先写要做什么,再解释为什么;标题直接表达要点,如“Set SAML before adding users”,避免“SAML configuration timing”这类含糊标题。
写作流程:起草时像对同事讲解一样写出步骤或说明;编辑时朗读检查语气,删去无助于读者的内容,确保每段只有一个明确目的,并验证示例确实可用;润色时使用描述性链接(不要用“here”),反引号仅用于代码或变量,粗体用于 UI 元素,使用美式拼写和序列逗号,图片尽量少且范围紧凑。
格式:编辑后运行 yarn prettier --write <file-path> 以统一格式。
常见模式:指令用代码块分步呈现,如先运行 command-to-run,再运行 next-command,不要把“记得先运行 X”埋在段落里;标题应具体,如“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;UI 元素写 Filter button 而非 Filter button;链接写 Check out the docs 而非 Click here。
限制:资料未提供安装方式、收费、平台支持或具体适用范围等更多信息。