docs-write

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

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).

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