Tag: Technical Writing
-
Strategy
How to Measure Whether Your Documentation Is Working
Pageviews tell you almost nothing about documentation: a page everyone reads twice may be a page nobody understands. Here are the four signals that do predict whether the docs are working, and…
-
Tooling
Diagrams in Documentation: When to Draw One, and What to Draw It With
A diagram earns its place when the thing being described is a shape: a sequence, a state machine, a topology. Everywhere else it is decoration that has to be maintained. Here is…
-
Guides
How to Write a Quickstart That Gets Someone to Working Code in Five Minutes
A quickstart has one job: get a reader from nothing to a verified, working result as fast as possible. Everything that does not serve that (background, alternatives, best practice) belongs on another…
-
Guides
How to Structure a Troubleshooting Guide That Actually Resolves Tickets
Organise a troubleshooting guide by symptom, not by subsystem: readers arrive with an error message, not a theory. Here is the anatomy of an entry that resolves a ticket, and how to…
-
Tooling
Documentation Search: Why Yours Doesn’t Work, and How to Fix It
Most documentation search fails for three fixable reasons: it indexes the wrong text, it does not know your synonyms, and it makes the reader leave the page to use it. Fix those…
-
Writing
Release Notes and Changelogs: How to Write Ones People Actually Read
A changelog records what changed; release notes explain what it means for the reader. Most teams write one document trying to be both, and it ends up serving neither. Here is how…
-
Guides
How to Version Your Documentation Without Losing Your Readers
Versioned documentation solves a real problem and creates three new ones: duplicated pages, split search results, and readers who land on a version they are not running. Here is when to version,…
-
Writing
How to Write a Documentation Style Guide People Actually Follow
A style guide only works if it is short enough to remember and enforced by something other than a reviewer’s memory. Here is what belongs in one, what to hand to a…
-
Guides
How to Write API Documentation Developers Actually Read
Every endpoint page has to answer four questions: what the call does, what it takes, what it returns, and what happens when it fails. Structure the page around those four and developers…
-
Guides
A WCAG 2.1 AA Checklist for Documentation Sites
Documentation sites fail accessibility in a small and predictable set of places. A working checklist of the WCAG 2.1 AA criteria docs actually trip on, the five failures we see most often,…
