Guides, migration stories and tooling notes for teams who publish their documentation.
Blog
-
Strategy Featured
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…
-
Migration
How to Migrate Confluence to a Public Documentation Site
A Confluence space is not a documentation site, and exporting one wholesale produces a mess. The migration that works is an audit first, a conversion to Markdown second, and a deliberate decision…
-
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…
