writing-guidelines

# Writing Guidelines Review the files or patterns provided by the user for compliance. Read files, check against rules below. Output concise but comprehensive: sacrifice grammar for brevity. High signal-to-noise. ## Rules ### Planning & content type - Every page has a plan (overview, goal, audience, content plan, open questions) referenced or linked - Content type declared in `meta.contentType`: `Tutorial`, `How-to`, `Reference`, `Conceptual`, `Troubleshooting`, or `Landing` - Title is user-shaped (the user's question), not feature-shaped (the engineer's name) - Page does one job: tutorial OR how-to OR reference, not three at once - Goal is verb-driven (Bloom's taxonomy): "configure", "explain", "debug" (testable) - Multi-audience pages: short shared opener, then technical subsections ### Voice & tone - Active voice. Mental test: append "by monkeys". If the sentence parses, rewrite - Direct address: `you`, never `the user` or `one can` - Imperative for steps: "Click **Add Project**", not "You will need to click **Add Project**" - Sentences under 20 words target - Contractions encouraged (`you'll`, `it's`) for warmth - Present tense unless describing future behavior - Limit `we`: only for deliberate organization actions ("we recommend", "we deprecated"), never as a stand-in for "you" - No rhetorical questions (sounds like marketing) - Second-read test: read each sentence once at speech pace; if you re-read to parse it, name the subject, the action, and the consequence (...