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.
Published
Documenting AI and Non-Deterministic Software
The unique challenge of writing documentation for products whose behavior changes based on input, context, and probability.
Prompt Engineering for Tech Writers
Practical prompt frameworks for documentation tasks.
The Technical Writer as Strategist
Moving from writing what you're asked for to shaping what gets asked.
The Technical Writer as Context Owner
AI can produce the documentation. Someone still has to know it's right.
Write Once, Publish Everywhere
The same procedure in three documents is three maintenance jobs. Single-sourcing makes it one.
Automated Linting and Consistency Checking
Let the machine hold the style guide in memory, so your reviewers can spend their attention on what it can't check.
Enforcing Style Guides Without Being a Cop
Don't write a house style from scratch. Adopt a base, document only where you diverge, and put it where writers already work.
Choosing Your Authoring Environment
How to evaluate what fits your team's needs.
The Shift to Docs-as-Code
What the most important toolchain shift in technical writing means for you.
Diagrams as Code: Mermaid & Draw.io
A diagram in a design tool goes stale in two years. A diagram in text gets reviewed in the pull request that changes it.
Visuals that work (and don't)
When an image earns its place, when it's just filling space, and why every screenshot you add is a bill that comes due.
Writing for Everyone: Accessibility
The guidelines run to hundreds of criteria. As a writer, you’ll touch the same three every day.
Words in the Machine: Intro to UX Writing
The words users read inside the product, while the docs stay closed.
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
Surviving the two-week sprint (September 14) · Task management and ticket systems (September 16) · Proving your worth: documentation metrics (September 18)
See the full outline — 35 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 · Writing for translation and localization · The technical writer as strategist
Phase 6 · AI
The technical 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