Our review

This skill guides writing documentation in Metabase's conversational, clear style, covering audience analysis, drafting, editing, and formatting.

Strengths

Provides concrete do/don't examples for common patterns.
Emphasizes reader-centered writing and concise, action-oriented headings.
Includes a practical editing checklist and a formatting command for consistency.
Catches common pitfalls like outdated numbers or broken code examples.

Limitations

Tied to a specific brand voice (Metabase), not universal.
Relies on an external style guide file for full context.
Focuses on prose docs, not API references or diagrams.

When to use it

Use when creating or editing user-facing documentation or help content that should match Metabase's tone.

When not to use it

Avoid for non-documentation writing like commit messages, marketing copy, or internal notes.

Examples

Draft a SAML setup guide

Write a step-by-step guide for setting up SAML in Metabase, following our docs style guide. Keep it conversational and user-focused. Use headings that state the point, and provide copy-pasteable commands.

Edit my draft to match style

Review my draft documentation for [feature]. Apply the Metabase style guide: simplify formal language, make headings action-oriented, fix links, and format code blocks properly. Also run prettier on the file.

Rewrite a paragraph in Metabase style

Rewrite the following documentation paragraph to match Metabase's conversational style. Use plain language and cut anything that doesn't help the reader: [paste text here]

name: docs-write description: Write documentation following Metabase's conversational, clear, and user-focused style. Use when creating or editing documentation files (markdown, MDX, etc.). allowed-tools: Read, Write, Grep, Bash, Glob

Documentation Writing Skill

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

When writing documentation

Start here

Who is this for? Match complexity to audience. Don't oversimplify hard things or overcomplicate simple ones.
What do they need? Get them to the answer fast. Nobody wants to be in docs longer than necessary.
What did you struggle with? Those common questions you had when learning? Answer them (without literally including the question).

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: bun run prettier --write <file-path>
This ensures consistent formatting across all documentation

Common patterns

Instructions:

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" ❌

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

Quick reference

| Write This | Not This | | -------------------------- | ------------------ | | 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 |

Metabase Documentation Writing

Recommended for