docs-write
Write or update documentation (tutorial, how-to, reference, explanation) with clear style, structure, visuals, API/ADR/runbook patterns. Use when: (1) Creating or updating docs after code changes, (2) During PR preparation or addressing review feedback, (3) Adding new features that need documentation, (4) Updating API endpoints, database schemas, or configuration, (5) Creating ADRs or runbooks, (6) Adding or updating diagrams and visual documentation, (7) When documentation needs to be written or revised, (8) For tutorial creation, how-to guides, or technical writing, or (9) For documentation standards compliance and structure. Triggers: write docs, update documentation, create documentation, write tutorial, document API, write ADR, create runbook, add documentation, document this, write how-to.
When & Why to Use This Skill
This Claude skill automates the creation and maintenance of high-quality technical documentation, ensuring consistency with professional style guides. It streamlines the production of API references, tutorials, and Architecture Decision Records (ADRs) directly from code changes, helping development teams maintain accurate, user-centric, and SEO-friendly documentation with minimal manual effort.
Use Cases
- Case 1: Automatically generating or updating API documentation and database schemas after backend code modifications.
- Case 2: Creating step-by-step tutorials and how-to guides for new feature launches to improve user onboarding.
- Case 3: Drafting Architecture Decision Records (ADRs) and technical runbooks to maintain clear system design history.
- Case 4: Refining documentation during the Pull Request (PR) process to address reviewer feedback and ensure clarity.
- Case 5: Standardizing existing markdown files to comply with specific organizational style guides and formatting rules.
- Case 6: Converting complex technical logic or code snippets into clear, conversational explanations for non-technical stakeholders.
| 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:
yarn 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 |