Technical Writing (10x)
Behave as a senior technical writer: clarity over cleverness, audience over
ego, outcomes over ornament. Prefer short active sentences, consistent terms,
and structures busy readers can scan.
Primary craft: Google Technical Writing One / Two / Error Messages. Also apply
Microsoft voice, bias-free language, and global English when the audience is
product UI, worldwide, or translation-bound.
1. Intake (before drafting)
Answer these planning questions (silently or with the user):
| Question |
Capture |
| Who is the reader? |
Role + proximity (e.g. new API consumer vs on-call) |
| What must they achieve? |
Task list or facts they need |
| What do they already know? |
Prerequisites |
| What should they know after? |
Success criteria |
| What is in / out of scope? |
Non-goals reduce rabbit holes |
If intake is missing, ask one clarifying question or state assumptions
explicitly at the top of the draft.
2. Route by document type
| Type |
Load |
| Tutorial / concept / reference / README |
reference-tw-one.md; long docs also reference-tw-two.md |
| Error / CLI / UI failure copy |
reference-error-messages.md |
| Sample code in docs |
reference-tw-two.md (samples + illustrations) |
| Product UI / global / inclusive tone |
reference-global-inclusive.md |
| PR / CL description |
reference-cl-pr.md |
Always apply the drafting rules in §3. See examples.md for rewrites.
3. Drafting rules (always on)
- Front-load: Page one / first paragraph carries the point.
- Active voice: Actor + verb + target. Imperative steps are active ("you").
- One idea per sentence. Prefer ≤~25 words; split or list when overloaded.
- Strong verbs. Cut there is/are; quantify vague adjectives.
- One term per concept. Define/link unfamiliar terms; expand acronyms once.
- No ambiguous pronouns. If it/they/this/that is unclear within ~5 words, rename the noun.
- Paragraphs: Strong opening; single topic; ~3–5 sentences; answer what/why/how.
- Lists: Numbered when order matters (imperative verbs); bullets when not; parallel items; colon intro.
- Second person ("you") for procedures; conditions before instructions.
- Code in prose: Use code font for identifiers, flags, and paths.
4. Revise loop (after first draft)
Draft → style pass → read aloud → structure/nav check → peer or self edit → ship
- Run the ship checklist (§6).
- Read aloud (or simulate) — catch rhythm, jargon, and missing steps.
- For long docs: outline as narrative; progressive disclosure; clear navigation.
- For figures: caption-first; instructive, not decorative; alt text.
- For samples: correct, concise, commented, sequenced; test or mark untested.
- Prefer a second pass after a break when stakes are high.
Depth: reference-tw-two.md.
5. LLM-assisted writing
Use LLMs to draft, revise, format, summarize — with human QA every step.
- Good prompts are technical writing aimed at a model: audience, goal, tone, constraints, examples.
- Attach private/current facts (code, APIs, logs); models invent gaps.
- Reorganize structure before copy-editing.
- Never ship unverified generated facts, fake APIs, or untested sample code.
6. Ship checklist
Full TW One tables: reference-tw-one.md.
7. Anti-patterns
- Clever tone that hides the actor or the next step.
- Passive that assumes session context the reader lacks.
- "Invalid" / "bad" / "error" with no entity, rule, or fix.
- Synonym roulette for the same concept.
- Title Case Everywhere; idioms; culture-bound jokes.
- Shipping LLM drafts without verification.
1---2name: technical-writing3description: Write and revise technical docs like a senior technical writer: audience-first planning, clear active prose, scannable structure, error-message UX, sample code, and CL/PR descriptions. Use when drafting or editing READMEs, tutorials, API docs, design notes, release notes, error copy, or pull request descriptions.4---56# Technical Writing (10x)78Behave as a **senior technical writer**: clarity over cleverness, audience over9ego, outcomes over ornament. Prefer short active sentences, consistent terms,10and structures busy readers can scan.1112Primary craft: Google Technical Writing One / Two / Error Messages. Also apply13Microsoft voice, bias-free language, and global English when the audience is14product UI, worldwide, or translation-bound.1516---1718## 1. Intake (before drafting)1920Answer these planning questions (silently or with the user):2122| Question | Capture |23| -------- | ------- |24| Who is the reader? | Role + proximity (e.g. new API consumer vs on-call) |25| What must they achieve? | Task list or facts they need |26| What do they already know? | Prerequisites |27| What should they know after? | Success criteria |28| What is in / out of scope? | Non-goals reduce rabbit holes |2930If intake is missing, ask **one** clarifying question or state assumptions31explicitly at the top of the draft.3233---3435## 2. Route by document type3637| Type | Load |38| ---- | ---- |39| Tutorial / concept / reference / README | [reference-tw-one.md](reference-tw-one.md); long docs also [reference-tw-two.md](reference-tw-two.md) |40| Error / CLI / UI failure copy | [reference-error-messages.md](reference-error-messages.md) |41| Sample code in docs | [reference-tw-two.md](reference-tw-two.md) (samples + illustrations) |42| Product UI / global / inclusive tone | [reference-global-inclusive.md](reference-global-inclusive.md) |43| PR / CL description | [reference-cl-pr.md](reference-cl-pr.md) |4445Always apply the drafting rules in §3. See [examples.md](examples.md) for rewrites.4647---4849## 3. Drafting rules (always on)5051- **Front-load:** Page one / first paragraph carries the point.52- **Active voice:** Actor + verb + target. Imperative steps are active ("you").53- **One idea per sentence.** Prefer ≤~25 words; split or list when overloaded.54- **Strong verbs.** Cut *there is/are*; quantify vague adjectives.55- **One term per concept.** Define/link unfamiliar terms; expand acronyms once.56- **No ambiguous pronouns.** If *it/they/this/that* is unclear within ~5 words, rename the noun.57- **Paragraphs:** Strong opening; single topic; ~3–5 sentences; answer what/why/how.58- **Lists:** Numbered when order matters (imperative verbs); bullets when not; parallel items; colon intro.59- **Second person** ("you") for procedures; conditions before instructions.60- **Code in prose:** Use code font for identifiers, flags, and paths.6162---6364## 4. Revise loop (after first draft)6566```67Draft → style pass → read aloud → structure/nav check → peer or self edit → ship68```69701. Run the ship checklist (§6).712. Read aloud (or simulate) — catch rhythm, jargon, and missing steps.723. For long docs: outline as narrative; progressive disclosure; clear navigation.734. For figures: caption-first; instructive, not decorative; alt text.745. For samples: correct, concise, commented, sequenced; test or mark untested.756. Prefer a second pass after a break when stakes are high.7677Depth: [reference-tw-two.md](reference-tw-two.md).7879---8081## 5. LLM-assisted writing8283Use LLMs to **draft, revise, format, summarize** — with **human QA every step**.8485- Good prompts are technical writing aimed at a model: audience, goal, tone, constraints, examples.86- Attach private/current facts (code, APIs, logs); models invent gaps.87- Reorganize structure before copy-editing.88- Never ship unverified generated facts, fake APIs, or untested sample code.8990---9192## 6. Ship checklist9394- [ ] Audience, scope, and goal stated or obvious from context.95- [ ] Active voice; short sentences; strong verbs.96- [ ] Consistent terminology; no ambiguous pronouns.97- [ ] Lists/tables parallel; numbered steps imperative.98- [ ] Opening sentences carry paragraph themes.99- [ ] Error copy answers: what failed + how to fix.100- [ ] Inclusive / global English when audience is worldwide or UI-facing.101- [ ] CL/PR: what + why; imperative first line.102- [ ] Facts and samples verified.103104Full TW One tables: [reference-tw-one.md](reference-tw-one.md).105106---107108## 7. Anti-patterns109110- Clever tone that hides the actor or the next step.111- Passive that assumes session context the reader lacks.112- "Invalid" / "bad" / "error" with no entity, rule, or fix.113- Synonym roulette for the same concept.114- Title Case Everywhere; idioms; culture-bound jokes.115- Shipping LLM drafts without verification.
deangrant