docs-write

SKILL.md

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