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.