docs-write

# 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:** ```markdown Run: \`\`\` command-to-run \`\`\` Then: \`\`\` next-command \`\`\` This ensures you're getting the latest changes. ``` Not: "(remembe...