Documentation Writing
FreeStreamline your documentation with a user-focused approach.
Free · Opens the source repo
What Documentation Writing does
The Documentation Writing skill is designed to help developers and technical writers create clear, concise, and user-friendly documentation in line with Metabase's established style guide. This skill emphasizes the importance of understanding the audience and tailoring content to their needs, ensuring that complex topics are explained without oversimplification and that simple concepts are not overcomplicated. By focusing on clarity and directness, this skill aids in producing documentation that helps users find answers quickly, without unnecessary detours.
The writing process outlined in this skill encourages users to draft documentation as if they were explaining it to a colleague, leading with actionable steps followed by explanations. This approach not only enhances readability but also ensures that each section of the documentation serves a specific purpose. The editing phase includes practical tips such as reading the text aloud to check for formality and clarity, cutting extraneous information, and verifying that examples provided are accurate and functional. This results in polished documentation that is both informative and engaging.
In addition to drafting and editing, the skill provides formatting guidelines to ensure consistency across documentation files. Users are instructed to run formatting tools like Prettier to maintain a uniform style, which is crucial for professional documentation. The skill also highlights common pitfalls to avoid, such as vague headings and overly formal language, reinforcing the goal of creating approachable content that resonates with users.
Overall, this skill is ideal for anyone involved in creating or editing documentation, particularly those working within the Metabase ecosystem. It serves as a comprehensive guide to producing effective documentation that prioritizes user experience and clarity, making it a valuable resource for technical communicators.
When to use it
Use this skill when creating or editing documentation files to ensure clarity and user-friendliness, especially in a technical context.
When not to use it
This skill may not be suitable for highly specialized documentation that requires deep technical jargon or for audiences that are already experts in the subject matter.
What you can build with it
Creating User Guides
Use this skill to draft user guides that are straightforward and easy to navigate, ensuring users can quickly find the information they need.
Editing Existing Documentation
When revising documentation, apply the editing tips to enhance clarity and remove unnecessary complexity.
Formatting Documentation Files
Utilize the formatting guidelines to ensure your documentation is consistently styled and professional.
How to install Documentation Writing
View source1. Install with the skills CLI
npx skills add metabase/metabase/docs-write --agent claude-code2. Or install it manually
Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.
Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs
Inside SKILL.md
Written by metabaseDocumentation 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 |
Frequently asked questions about Documentation Writing
Similar skills
Supabase Docs Authoring
Streamline your Supabase documentation process.
Docs Writer
Streamline your documentation process with precision.
Clinical Case Report
Generate structured medical case presentations.
CrossFrame Suite
Streamline complex workflows for Chinese structural analysis.
Em Dash Expert
Master the em dash for clear, precise writing.
Nature Statistics Reporting
Enhance manuscript statistics for high-impact journal submissions.