docs-write

metabase's avatarfrom metabase

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

⭐44.7kstars🔀6.0kforks📁View on GitHub🕐Updated Nov 25, 2025
[Technical Writing]

When & Why to Use This Skill

This Claude skill automates the creation and refinement of technical documentation by adhering to a conversational, user-focused style guide. It ensures that markdown and MDX files are clear, accessible, and professionally formatted, helping teams produce high-quality documentation that prioritizes the reader's experience and quick problem-solving.

Use Cases

  • 1. Technical Documentation Drafting: Creating clear, step-by-step guides for software features that match complexity to the target audience's needs.
  • 2. Content Refinement and Editing: Rewriting existing documentation to remove formal jargon, simplify language, and ensure a conversational tone that sounds like a peer-to-peer explanation.
  • 3. Style Guide Enforcement: Auditing documentation to ensure consistent use of American spelling, descriptive links, and proper formatting for UI elements and code blocks.
  • 4. Automated Markdown Formatting: Utilizing integrated tools like Prettier to maintain consistent code structure and visual layout across all documentation files.
namedocs-write
descriptionWrite documentation following Metabase's conversational, clear, and user-focused style. Use when creating or editing documentation files (markdown, MDX, etc.).
allowed-toolsRead, 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

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:

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