# Docs Write

Write documentation following Metabase's conversational, clear, and user-focused style.

- Repository: https://github.com/foryourhealth111-pixel/Vibe-Skills (3789 stars)
- Category: Writing
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add foryourhealth111-pixel/Vibe-Skills --skill docs-write -g -a claude-code -y`
Codex: `npx skills add foryourhealth111-pixel/Vibe-Skills --skill docs-write -g -a codex -y`
Cursor: `npx skills add foryourhealth111-pixel/Vibe-Skills --skill docs-write -g -a cursor -y`
Gemini CLI: `npx skills add foryourhealth111-pixel/Vibe-Skills --skill docs-write -g -a gemini-cli -y`

## Description

Write documentation following Metabase's conversational, clear, and user-focused style. Use when creating or editing documentation files (markdown, MDX, etc.).

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

**Format:**

- Run prettier on the file after making edits: `yarn prettier --write <file-path>`
- This ensures consistent formatting across all documentation

### Common patterns

**Instructions:**

```markdown
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](link)" ✅
- "Read the docs [here](link)" ❌

### Watch out for

The rest: https://github.com/foryourhealth111-pixel/Vibe-Skills/blob/HEAD/bundled/skills/docs-write/SKILL.md