techwrite

# Technical Writing (Deep Workflow) Technical writing succeeds when **readers can act** or **decide** with less confusion. Optimize for **clarity**, **correctness**, and **appropriate depth**—not word count. ## When to Offer This Workflow **Trigger conditions:** - New feature docs, migration guides, API references - RFCs, ADRs, architecture summaries - Runbooks, onboarding docs, postmortems (writing-heavy) - “Make this clearer” edits on existing pages **Initial offer:** Use **six stages**: (1) define audience & goal, (2) outline & scope, (3) draft core content, (4) examples & edge cases, (5) review for clarity, (6) ship & maintain. Ask for **template** or **style guide** if org has one. --- ## Stage 1: Audience & Goal **Goal:** One primary reader persona; one **outcome**. ### Questions 1. **Who** reads (new hire, partner engineer, SRE, end user of API)? 2. **Job-to-be-done**: debug issue? integrate API? approve design? 3. **Constraints**: word limit, legal review, localization later? ### Anti-goals - “Everyone” audience → usually **nobody** satisfied—prefer layered docs (overview + deep dive links) **Exit condition:** **Success sentence**: “After reading, the reader can ___.” --- ## Stage 2: Outline & Scope **Goal:** **BLUF** + **sections** that match mental model. ### Practices - **Top**: context + outcome + prerequisites - **Middle**: procedural steps OR conceptual model—pick one primary mode per doc - **Bottom**: troubleshooting, FAQ, links, changelog ### Scope control - **In scope / out of scope** box for ambiguous topics - **Version** and **last reviewed** metadata for fast-moving products **Exit condition:** Outline reviewed; **order** matches reader journey (often happy path first). --- ## Stage 3: Draft Core Content **Goal:** **Precise**, **scannable**, **honest**. ### Style - **Short sentences**; **active voice** for procedures (“Click…”, “Run…”) - **Define terms** on first use; **glossary** for large docs - **Avoid** vague adjectives (“robust”, “seamless”) without criteria ### Structure signals - **Headings** that describe content; **lists** for sequences and parallel items - **Numbered steps** for order-sensitive actions **Exit condition:** First full pass complete—**ugly OK**, precision matters more than polish. --- ## Stage 4: Examples & Edge Cases **Goal:** Examples **reduce tickets**; edge cases **build trust**. ### Examples - **Minimal complete** snippet; **realistic** names; **expected output** - Show **failure** example when errors are common—include **how to fix** ### Edge cases - Permissions, rate limits, idempotency, backward compatibility - **“If you see X, do Y”** troubleshooting table when helpful **Exit condition:** At least one **end-to-end** path works on fresh machine (when procedural). --- ## Stage 5: Review for Clarity **Goal:** Remove **ambiguity** and **hidden assumptions**. ### Checklist - **Ambiguous pronouns** (“it”, “this”)—replace with nouns - **Implied steps**—make explicit - **Diagrams**: labeled arrows; **alt text** for accessibility - **Links**: avoid broken anchors; prefer **stable** URLs ### Reviews - **Peer review** for technical accuracy; **non-expert** read for onboarding docs **Exit condition:** Another reader can follow without asking clarifying questions—or questions are **FAQ’d**. --- ## Stage 6: Ship & Maintain **Goal:** Docs **decay**—plan updates. ### Practices - **Owner** field; **review cadence** for critical paths - **Changelog** or **page history** when platform changes often - **Deprecate** old pages with redirects --- ## Final Review Checklist - [ ] Audience and success outcome explicit - [ ] Outline matches reader journey - [ ] Procedures numbered; concepts separated from steps - [ ] Examples + failures where needed - [ ] Reviewed for ambiguity; diagrams accessible ## Tips for Effective Guidance - Prefer **concrete nouns** over abstractions (“the database primary” vs “the system”). - When user pastes draft, do **surgical** edits—preserve voice unless clarity suffers. - For **non-native readers**, avoid idioms and culture-specific jokes. ## Handling Deviations - **Marketing-heavy request**: separate **facts** from positioning; flag risky claims. - **Legal-sensitive**: suggest expert review; avoid drafting binding language unless qualified.