Skip to main content
ScaleMath

Documentation grows around tickets, releases and search terms. Almost never around what a user needs.

This is the method we use to stop that happening, and to fix it where it already has: a practical method for deciding what documentation should exist, fixing the library you have already got, and deciding what has to be true before anything is published.

Start reading

Introduction

What the method is for, and the question everything else answers.

  1. What this method is forDocumentation grows around tickets, releases and search terms rather than user needs. This is how we stop that, and fix it where it has already happened.

Foundation

The four types the method rests on, how we apply them, and why we plan up front.

  1. Start from the four typesDocumentation does not have one purpose. It has four, each answering a different user need, and collapsing them is what makes a library hard to use.
  2. One primary job per pageReal libraries do not divide cleanly into four isolated forms. Each page gets one primary job, and limited supporting material stays when it helps that page do it.
  3. Plan the structure, gate the publishThe usual advice is to let structure emerge from small improvements. Real work has a scope, a reviewer and a date, so we plan up front and gate publication.

Principles

The ten rules the rest of the method rests on, and how to break the ties between them.

  1. The ten principlesThe rules that guide every decision across new documentation, updates, audits, rewrites and restructures. Meant to be applied together, not as isolated tests.
  2. Resolve conflicting principlesTwo pairs of principles contradict each other in ordinary use. A method that does not rank them produces a library that contradicts itself.

Classify

How to decide what kind of page you are writing, what each kind demands, and where the content that fits none of them belongs.

  1. Use the classifierTwo mechanical questions that decide the type of a page, and what it means when neither answer is clear.
  2. Write tutorials that teachA tutorial is defined by the teaching relationship, not by the reader being a beginner. The commonest failure is a how-to guide wearing the wrong label.
  3. Write guides that get out of the wayIn a how-to guide the user sets the goal. Keep the explanation that prevents a mistake and cut the rest.
  4. Make reference scannableReference is primarily designed for retrieval, not continuous reading. Structure it to match the product, and keep the lookup out of prose.
  5. Explain before you teachExplanation is not only what comes after a tutorial. A reader who lacks the model of a system will not get through the tutorial at all.
  6. Place what does not fitFAQs, glossaries, changelogs, examples and generated reference. Every real library has them and the four types do not describe them.

Work an existing library

Almost no documentation work starts from an empty page. This is what happens to the pages that are already there.

  1. Split only for a reasonLength is not a reason. Split when a page serves distinct user needs that can stand on their own, and keep material together when separating it adds friction.
  2. Merge what overlapsOverlapping pages create uncertainty about which one is current. Pick the strongest, absorb any useful material from the rest, then redirect the redundant pages.
  3. Repeat only what is cheap to maintainSome duplication saves the reader a pointless click. The test is not length, it is what happens the next time the product changes.
  4. Handle audiences and versionsTwo audiences do not automatically mean two pages, and old documentation earns its place only while somebody still needs it.
  5. Organise by what users doThe four types describe pages, not navigation. A sidebar named after them forces the reader to know the answer before they can look.

Write and publish

House standards for the prose itself, the line between tested and asserted, and the checks a page passes before it ships.

  1. Hold the writing standardsPrerequisites, voice, scanability, accessibility and terminology. A technically complete document that cannot be scanned is not finished.
  2. Warn by risk, not frequencyA warning that affects one user in a thousand still belongs at the top if ignoring it destroys their data. Plus where troubleshooting and screenshots earn their place.
  3. Separate tested from assertedEvery draft ships with a list saying which claims were run, which were confirmed in writing, and which are neither. Nothing publishes on the third.
  4. Challenge the requestA request for a page is an input, not a specification. Find the user problem first, then recommend the structure that serves it.
  5. Measure where measurement is meaningfulWhere suitable data exists, agree what success looks like before the work starts. Some of documentation’s value is real but hard to attribute precisely.
  6. Pass the publication gateTen questions, all of which are a yes before anything goes live. Technically correct is not the same as finished.

Need this applied to your documentation?

We audit, restructure and write product documentation for B2B software companies.

Product documentation servicesRun a free documentation audit
ScaleMath
  • Full stack, senior team: you get us, not just one person that's good at one thing.
  • Your strategic partner: we're here to serve you. Get our input on strategy, product, customer experience, UX, and more.
  • We've helped renowned companies like:
AtarimAAWPWP Fusion