writing-guidelines

1# Writing Guidelines
2 
3Review the files or patterns provided by the user for compliance.
4 
5Read files, check against rules below. Output concise but comprehensive: sacrifice grammar for brevity. High signal-to-noise.
6 
7## Rules
8 
9### Planning & content type
10 
11- Every page has a plan (overview, goal, audience, content plan, open questions) referenced or linked
12- Content type declared in `meta.contentType`: `Tutorial`, `How-to`, `Reference`, `Conceptual`, `Troubleshooting`, or `Landing`
13- Title is user-shaped (the user's question), not feature-shaped (the engineer's name)
14- Page does one job: tutorial OR how-to OR reference, not three at once
15- Goal is verb-driven (Bloom's taxonomy): "configure", "explain", "debug" (testable)
16- Multi-audience pages: short shared opener, then technical subsections
17 
18### Voice & tone
19 
20- Active voice. Mental test: append "by monkeys". If the sentence parses, rewrite
21- Direct address: `you`, never `the user` or `one can`
22- Imperative for steps: "Click **Add Project**", not "You will need to click **Add Project**"
23- Sentences under 20 words target
24- Contractions encouraged (`you'll`, `it's`) for warmth
25- Present tense unless describing future behavior
26- Limit `we`: only for deliberate organization actions ("we recommend", "we deprecated"), never as a stand-in for "you"
27- No rhetorical questions (sounds like marketing)
28…