- name
- techwrite
- description
- Deep workflow for technical prose—audience, purpose, structure, precision, examples, diagrams, review, and iteration. Use when drafting developer docs, design notes, internal guides, RFCs, or public technical articles.
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
- Who reads (new hire, partner engineer, SRE, end user of API)?
- Job-to-be-done: debug issue? integrate API? approve design?
- 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.