--- name: docs-review description: Review documentation changes for compliance with the Metabase writing style guide. Use when reviewing pull requests, files, or diffs containing documentation markdown files. allowed-tools: Read, Grep, Bash, Glob --- # Documentation Review Skill # Metabase Writing Style Guide ## Core Principles Write like you're talking to a colleague. Be conversational, not formal. Get people what they need quickly. Know your audience and match the complexity. ## Tone and Voice **Do:** - Use contractions ("can't" not "cannot") - Say "people" or "companies" instead of "users" - Be friendly but not peppy - Acknowledge limitations honestly ("that's on us, not them") - Jokes and Easter eggs are okay (permit them, don't suggest them) **Don't:** - Use exclamation points excessively - Rely on tired tropes about nerdiness - Use corporate jargon ("utilize", "offerings", "actionable insights") - Tell people something is cool (show them instead) ## Structure and Clarity **Lead with the important stuff:** - Most important information first - Lead with the ask, then provide context - Cut text that adds little value (when in doubt, cut it) - Each paragraph should have one clear purpose **Make headings do the work:** - Convey your actual point, not just the topic - "Use headings to highlight key points" not "How to write a good heading" - Use sentence case, no punctuation except question marks - No links in headings unless entire heading is a link ## Instructions and Examples **Tell people what to do:** - Give the action before explaining why - Put commands in execution order - Provide context, steps, and reasoning - Don't describe tasks as "easy" or "simple" **Answer unasked questions:** - Include answers to "dumb" questions you had when learning - Don't literally include the question, just give the answer ## Formatting **Code vs. UI elements:** - Backticks for code, variable names, parameters only - **Bold** for UI elements and labels (e.g., "Click the **Save** button") - Don't use backticks or quotes for UI elements ## Writing Mechanics - Limit pronouns when introducing new terms (repeat the term to reinforce it) - Ampersands only in proper nouns, never as substitute for "and" ## Terminology Preferences Use familiar terms from tools people already know: - "Summarize" (like Excel) instead of "aggregate" - "Take a look at" instead of "reference" - "Filter" instead of technical database terms when appropriate ## Red Flags Avoid these patterns: - Multiple exclamation points - Linking "here" - Bullet lists to explain (use prose) - Numbers that will change (guard against change) - Describing things as "easy" or "simple" - Stock photography-worthy content ## 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) ## 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 ## 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 ## Quick scan table | Pattern | Issue | | ----------------------------- | --------------------------------------------- | | we can do X, our feature | Should be "Metabase" or "it" | | click here, read more here | Need descriptive link text | | easy, simple, just | Remove condescending qualifiers | | users | Should be "people" or "companies" if possible | ## 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. ### Local review mode format When outputting issues in the conversation (local mode), use this format: ```markdown ## 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" ### PR review mode format 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 ## 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).