docs-writelisted

# Documentation Writing Skill # Metabase Writing Style Guide ## Core Principles Write like you're talking to a colleague. Be conversational, not formal. Get people what they need quickly. Know your audience and match the complexity. ## Tone and Voice **Do:** - Use contractions ("can't" not "cannot") - Say "people" or "companies" instead of "users" - Be friendly but not peppy - Acknowledge limitations honestly ("that's on us, not them") - Jokes and Easter eggs are okay (permit them, don't suggest them) **Don't:** - Use exclamation points excessively - Rely on tired tropes about nerdiness - Use corporate jargon ("utilize", "offerings", "actionable insights") - Tell people something is cool (show them instead) ## Structure and Clarity **Lead with the important stuff:** - Most important information first - Lead with the ask, then provide context - Cut text that adds little value (when in doubt, cut it) - Each paragraph should have one clear purpose **Make headings do the work:** - Convey your actual point, not just the topic - "Use headings to highlight key points" not "How to write a good heading" - Use sentence case, no punctuation except question marks - No links in headings unless entire heading is a link ## Instructions and Examples **Tell people what to do:** - Give the action before explaining why - Put commands in execution order - Provide context, steps, and reasoning - Don't describe tasks as "easy" or "simple" **Answer unasked questions:** - Include an