The Writers' Table
A reading and practice group, not a course. Each post covers one topic and ends with an exercise. Work through them in any order.
The articles aren't exhaustive. They're designed to give you a starting point, with references for further exploration.
Three posts per week — Monday, Wednesday, and Friday.
Free, no pledge. Articles post to The Way We Write Now on Substack. If the subscription page offers a pledge option, choose No Pledge.
Published
Code Samples and Code Comments
The most verifiable thing you'll write, and the most likely to rot — here's how to keep samples current.
From Git Commits to Release Notes
A commit says a change happened. A release note says what it means — and the only way to bridge them is to ask.
What the Generator Can't Write
The tool generates the reference. The judgment, the examples, and the spec itself are still yours.
API Docs 101: Demystifying REST
You don't need to write production code. You need the vocabulary, an API client, and one successful request.
Documentation Metadata and Taxonomy
The infrastructure that makes content findable and usable by both humans and AI systems.
Documentation Stop the Sprawl: Information Architecture
Structure documentation so users can find what they need.
Documentation Frameworks: A Field Guide
Diátaxis is the one to start with, but DITA, minimalism, and others fill the gaps it leaves open.
Review and Approval Workflows
Designing a review cycle that ends, and getting sign-off from people who'd rather not give it.
Working with SMEs
Without losing your mind..
The Passive Voice Myth
What the rule actually protects against, and when passive is correct.
The Three Tiers of Editing
Developmental, copy, and mechanical — and why conflating them wastes reviewer time.
Plain Language Is Not Dumbing Down
Precision and simplicity are the same goal, not a tradeoff.
Writing for the F-Pattern
How people actually scan a page, and what that means for structure.
Mastering Audience Analysis
Includes the companion persona workbook.
What Technical Writers Actually Do
The job as it exists now, not as the job title suggests.
Coming Next
Intro to UX Writing (August 17) · Writing for Everyone: Accessibility (August 19) · Visuals that work (and don't) (August 21)
See the full outline — 36 articles across 8 phases
Phase 1 · Foundation
What the job is · Writing craft · Editing
Phase 2 · Working with people & structure
The psychology of the SME · Review and approval workflows · Documentation frameworks · Information architecture · Metadata and taxonomy
Phase 3 · Content types — what you produce
API docs 101: demystifying REST · Beyond REST: OpenAPI and Swagger · From Git commits to release notes · Code samples and code comments · Intro to UX writing · Writing for everyone: accessibility · Visuals that work (and don't) · Diagrams as code: Mermaid and Draw.io
Phase 4 · The modern toolchain
The shift to docs-as-code · Choosing your authoring environment · Enforcing style guides without being a cop · Automated linting and consistency checking
Phase 5 · Scale & strategy
Write once, publish everywhere · Modular docs and the philosophy of DITA · Writing for translation and localization · The technical writer as strategist
Phase 6 · AI
The writer as context owner · Prompt engineering for tech writers · Documenting AI and non-deterministic software
Phase 7 · Process, metrics & maintenance
Surviving the two-week sprint · Task management and ticket systems · Proving your worth: documentation metrics · The art of deleting: content audits
Phase 8 · Career
Building the NDA-proof portfolio · Contracting vs. full-time