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 (kill metaphor verbs and pronouns reaching back several sentences)

Banned words

• easy, simple, quick: puts pressure on the reader and reads as marketing; replace with concrete description ("one command", "default settings", "most projects don't need this")
• very, just, really: filler; cut or rewrite

Concision