technical-writer

Technical writing craft rules

Apply these rules when producing or editing developer documentation prose. Follows the spirit of the Google Developer Documentation Style Guide without being tied to any one brand guide. Complements the Diátaxis framework: Diátaxis tells you which quadrant (tutorial, how-to, reference, explanation) a page belongs to; these rules tell you how to write each sentence once the quadrant is fixed.

When to apply

Trigger when the user is:

• Writing a new docs page (tutorial, how-to, reference entry, explanation, getting-started, README, migration guide).
• Reviewing or revising an existing docs page for quality.
• Diagnosing why a docs page feels flat, bloated, or confusing.

Skip for: commit messages, PR descriptions, ADRs, internal design docs, code comments. Those have their own registers.

Structure rules

1. Open with a one-sentence summary. The first line must tell the reader what they will learn or accomplish. If removing the opening sentence leaves the page's purpose unclear, it was doing work.
2. H2 sections as scannable signposts. Each heading is a promise: the reader should know what they'll get from the section without reading it. Prefer verb-led headings for task pages, noun phrases for reference.
3. Order by frequency, not logic. Most common use case first, edge cases last. A reader who stops reading halfway should still have hit the 80% path.
4. Inverted pyramid within each section. Lead with the most important sentence. Supporting detail follows. Caveats and edge cases end the section.
5. One topic per H2. If a section covers two things, split it. Skim readers rely on the heading matching the content.

Voice and register

• Active voice, present tense. "Bedrock reads the config" beats "The config is read by bedrock." Passive is acceptable only when the agent genuinely doesn't matter.
• Second person for instructions ("you configure"), third person for concepts ("bedrock configures"). Do not mix within a section.
• Sentence case headings. Proper nouns keep their capitals.
• Concrete over abstract. Name the file, the function, the command. "Run pnpm build" beats "build the project."
• No filler openers. Cut "In order to", "It is important to note that", "Please note that", "Basically".