Back to Details

docs-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Review Skill

文档审查技能

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

Review mode detection

审查模式检测

IMPORTANT: Before starting the review, determine which mode to use:
  1. PR review mode: If the 
    mcp__github__create_pending_pull_request_review
    tool is available, you are reviewing a GitHub PR
    • Use the pending review workflow to post all issues as one cohesive review
    • Follow the workflow steps in "PR review mode format" below
  2. Local review mode: If the MCP tool is NOT available, output issues in the conversation
    • Format all issues in a numbered markdown list (as described in "Feedback format" below)
重要提示：开始审查前，请确定要使用的模式：
  1. PR审查模式：如果
    mcp__github__create_pending_pull_request_review
    工具可用，说明你正在审查GitHub PR
    • 使用待处理审查工作流，将所有问题作为一个连贯的审查内容发布
    • 遵循下方“PR审查模式格式”中的工作流步骤
  2. 本地审查模式：如果MCP工具不可用，在对话中输出问题
    • 按照下方“反馈格式”中的说明，将所有问题格式化为编号Markdown列表

Review process

审查流程

  1. Detect review mode - Check if 
    mcp__github__create_pending_pull_request_review
    is available
  2. Read the changes through once to understand intent
  3. Check all issues that violate style guide or significantly impact readability
  4. Only flag issues worth mentioning - if it won't make a material difference to the reader, skip it
  5. REQUIRED: Number ALL feedback sequentially - Start from Issue 1 and increment for each issue found
  1. 检测审查模式 - 检查
    mcp__github__create_pending_pull_request_review
    是否可用
  2. 通读变更内容，理解其意图
  3. 检查所有违反风格指南或严重影响可读性的问题
  4. 仅标记值得提出的问题——如果对读者没有实质性影响，可以忽略
  5. 必填要求：为所有反馈按顺序编号 - 从Issue 1开始，每发现一个问题就递增编号

Review checklist

审查检查清单

Run through the diff looking for these issues:
Tone and voice:
  • Formal/corporate language ("utilize" not "use", "offerings", etc.)
  • "Users" instead of "people" or "companies"
  • Excessive exclamation points or overly peppy tone
  • Telling readers something is cool instead of showing them
Structure and clarity:
  • Important information buried instead of leading
  • Verbose text that adds little value
  • Paragraphs without clear purpose
  • Vague headings that don't convey the point
  • Instructions explain "why" before telling "what to do"
  • Tasks described as "easy" or "simple"
Links and references:
  • Linking the word "here" instead of descriptive text
  • Links in headings (unless entire heading is a link)
Formatting:
  • Ampersands as "and" substitute (except proper nouns)
  • Inconsistent list formatting
Code and examples:
  • Code examples that don't work or would error
  • Commands not in execution order
  • Full-width screenshots instead of scoped UI elements
  • Excessive or unnecessary images
Sentence construction:
  • Overuse of pronouns when introducing new terms
逐一检查差异内容，寻找以下问题：
语气与措辞：
  • 正式/企业化语言（例如用“utilize”而非“use”，使用“offerings”等词汇）
  • 使用“Users”而非“people”或“companies”
  • 过多感叹号或过于活泼的语气
  • 告诉读者某个内容很酷，而非展示其价值
结构与清晰度：
  • 重要信息被隐藏，未放在显眼位置
  • 冗长且无实际价值的文本
  • 没有明确主题的段落
  • 模糊的标题，无法传达核心内容
  • 先解释“原因”再说明“要做什么”的说明文字
  • 将任务描述为“easy”或“simple”
链接与引用：
  • 使用“here”作为链接文字，而非描述性文本
  • 标题中包含链接（除非整个标题是一个链接）
格式：
  • 使用“&”代替“and”（专有名词除外）
  • 列表格式不一致
代码与示例：
  • 无法运行或会报错的代码示例
  • 命令顺序不符合执行逻辑
  • 全屏截图而非局部UI元素截图
  • 过多或不必要的图片
句子结构：
  • 引入新术语时过度使用代词

Quick scan table

快速扫描对照表

PatternIssue
we can do X, our featureShould be "Metabase" or "it"
click here, read more hereNeed descriptive link text
easy, simple, justRemove condescending qualifiers
usersShould be "people" or "companies" if possible
模式问题描述
we can do X, our feature应使用“Metabase”或“it”
click here, read more here需要使用描述性的链接文字
easy, simple, just删除带有优越感的限定词
users尽可能使用“people”或“companies”替代

Feedback format

反馈格式

MANDATORY REQUIREMENT: Every single issue MUST be numbered sequentially starting from Issue 1.
This numbered format is NON-NEGOTIABLE. It allows users to efficiently reference specific issues (e.g., "fix issues 1, 3, and 5") and track which feedback has been addressed.
强制要求：每一个问题都必须从Issue 1开始按顺序编号。
这种编号格式是不可协商的。它能让用户高效地引用特定问题（例如：“修复问题1、3和5”），并跟踪哪些反馈已被处理。

Local review mode format

本地审查模式格式

When outputting issues in the conversation (local mode), use this format:
markdown
undefined
在对话中输出问题（本地模式）时，请使用以下格式：
markdown
undefined

Issues

问题列表

Issue 1: [Brief title] Line X: Succinct description of the issue [code or example] Suggested fix or succinct explanation
Issue 2: [Brief title] Line Y: Description of the issue Suggested fix or explanation
Issue 3: [Brief title] ...

**Examples:**

> **Issue 1: Formal tone**
> Line 15: This could be more conversational. Consider: "You can't..." instead of "You cannot..."

> **Issue 2: Vague heading**
> Line 8: The heading could be more specific. Try stating the point directly: "Run migrations before upgrading" vs "Upgrade process"
Issue 1: [简短标题] 第X行：问题的简洁描述 [代码或示例] 建议的修复方案或简洁解释
Issue 2: [简短标题] 第Y行：问题描述 建议的修复方案或解释
Issue 3: [简短标题] ...

**示例：**

> **Issue 1: 正式语气问题**
> 第15行：这段文字可以更口语化一些。建议将“You cannot...”改为“You can't...”

> **Issue 2: 标题模糊**
> 第8行：标题可以更具体。建议直接点明核心内容：“升级前运行迁移”而非“升级流程”

PR review mode format

PR审查模式格式

When posting to GitHub (PR mode), use the pending review workflow:
Workflow steps:
  1. Start a review: Use 
    mcp__github__create_pending_pull_request_review
    to begin a pending review
    • This creates a draft review that won't be visible until submitted
  2. Get diff information: Use 
    mcp__github__get_pull_request_diff
    to understand the code changes and line numbers
    • This helps you determine the correct file paths and line numbers for comments
  3. Identify ALL issues: Read through all changes and identify every issue worth mentioning
    • Collect all issues before posting any comments
    • Number them sequentially (Issue 1, Issue 2, Issue 3, etc.)
  4. Add review comments: Use 
    mcp__github__add_pull_request_review_comment_to_pending_review
    for each issue
    • CRITICAL: Post ALL comments in a SINGLE response using multiple tool calls in parallel
    • Each comment should reference a specific file path and line number from the diff
    • Start each comment body with 
      **Issue N: [Brief title]**
    • Include the description and suggested fix
  5. Submit the review: Use 
    mcp__github__submit_pending_pull_request_review
    to publish all comments at once
    • Use event type 
      "COMMENT"
      (NOT "REQUEST_CHANGES") to make it non-blocking
    • Do NOT include a body message - Leave the body empty or omit it entirely
    • All comments will appear together as one cohesive review
Comment format example:
**Issue 1: Formal tone**

This could be more conversational. Consider: "You can't..." instead of "You cannot..."
IMPORTANT:
  • Each issue gets its own review comment attached to the pending review
  • Number ALL comments sequentially (Issue 1, Issue 2, Issue 3, etc.)
  • Always start the comment body with 
    **Issue N: [Brief title]**
  • MUST add all comments in parallel in a single response - Do NOT add them one after another in separate responses
  • Do NOT output a summary message to the conversation - only post GitHub review comments
  • When submitting the review, do NOT include a body parameter (or leave it empty) to avoid cluttering the PR with summary text
  • The review will appear as a single review with multiple comments when submitted
在GitHub上发布审查内容（PR模式）时，请使用待处理审查工作流：
工作流步骤：
  1. 开始审查：使用
    mcp__github__create_pending_pull_request_review
    启动一个待处理审查
    • 这会创建一个草稿审查，提交前不会对外可见
  2. 获取差异信息：使用
    mcp__github__get_pull_request_diff
    了解代码变更和行号
    • 这有助于确定评论对应的正确文件路径和行号
  3. 识别所有问题：通读所有变更内容，找出所有值得提出的问题
    • 在发布任何评论前，先收集所有问题
    • 按顺序编号（Issue 1、Issue 2、Issue 3等）
  4. 添加审查评论：对每个问题使用
    mcp__github__add_pull_request_review_comment_to_pending_review
    • 关键要求：在单个响应中通过并行调用多个工具，发布所有评论
    • 每条评论都应引用差异中的特定文件路径和行号
    • 每条评论的正文都以
      **Issue N: [简短标题]**
      开头
    • 包含问题描述和建议的修复方案
  5. 提交审查：使用
    mcp__github__submit_pending_pull_request_review
    一次性发布所有评论
    • 使用事件类型
      "COMMENT"
      （而非"REQUEST_CHANGES"），使其不会阻塞PR合并
    • 请勿添加正文消息 - 留空或完全省略正文
    • 所有评论会作为一个连贯的审查内容一起显示
评论格式示例：
**Issue 1: 正式语气问题**

这段文字可以更口语化一些。建议将“You cannot...”改为“You can't...”
重要提示：
  • 每个问题对应一条附加到待处理审查的评论
  • 所有评论都按顺序编号（Issue 1、Issue 2、Issue 3等）
  • 评论正文必须以
    **Issue N: [简短标题]**
    开头
  • 必须在单个响应中并行添加所有评论 - 请勿在单独的响应中逐个添加
  • 请勿在对话中输出总结消息 - 仅发布GitHub审查评论
  • 提交审查时，请勿包含body参数（或留空），避免PR中出现多余的总结文本
  • 提交后，所有评论会作为一个单独的审查内容显示

Final check

最终检查

  1. Remove any issues from your assessment that won't make a material difference to the reader if addressed. Only flag issues worth the author's time to fix.
  2. Verify all issues are numbered sequentially starting from Issue 1 with no gaps in numbering.
  3. Confirm the format exactly matches: 
    **Issue N: [Brief title]**
    where N is the issue number.
  4. In PR mode: Verify each issue was posted as a separate GitHub comment (not output to conversation).
  1. 从评估中移除那些即使修复也不会对读者产生实质性影响的问题。仅标记值得作者花时间修复的问题。
  2. 验证所有问题都从Issue 1开始按顺序编号，编号无缺失。
  3. 确认格式完全符合要求：
    **Issue N: [简短标题]**
    ，其中N是问题编号。
  4. PR模式下：验证每个问题都作为单独的GitHub评论发布（而非输出到对话中）。