Notre avis

Cette compétence guide la rédaction de documentation technique selon le style conversationnel et précis de Metabase, en mettant l'accent sur la clarté, la structure et l'audience.

Points forts

Fournit un guide de style complet avec des exemples concrets
Insiste sur l'écriture orientée action et la suppression des informations superflues
Inclut des vérifications automatiques de formatage avec Prettier
Encourage une relecture critique pour garantir l'exactitude des exemples

Limites

Principalement adapté au style de documentation de Metabase, peut nécessiter adaptation pour d'autres contextes
Ne gère pas la génération de diagrammes ou d'illustrations complexes
Suppose une familiarité de base avec Markdown et les outils de documentation

Quand l'utiliser

Utilisez cette compétence pour rédiger ou réviser toute documentation technique (Markdown, MDX) en suivant un style clair, conversationnel et centré sur l'utilisateur.

Quand l'éviter

Évitez cette compétence pour des tâches ne relevant pas de la documentation, comme le codage, les tests ou le déploiement.

Exemples

Write setup documentation

Write documentation for setting up Metabase with Docker. Use the Metabase style guide: start with who it's for, lead with actions, and use descriptive headings.

Revise existing docs for clarity

Revise this documentation paragraph to follow Metabase style: remove formal language, make links descriptive, and ensure each sentence has a clear purpose. The text: 'Users should first reference the configuration guide located at the following URL. Click here to access it.'

Create a how-to guide

Create a step-by-step guide on how to create a dashboard in Metabase. Use the patterns from the style guide: state the goal in the heading, lead with what to do, then explain why.

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

Use references/metabase-style-guide.md guide when writing or editing Metabase documentation. It sets the default tone, structure, and formatting so people can get answers fast and trust the steps.

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 |

Rédaction de Documentation

Recommandé pour