Documentation, explained.

The building blocks

Four kinds of page, four different readers

Almost every documentation set is some mix of these. Most of the trouble comes from writing one when the reader needed another.

• Someone who just signed up

  Getting started

  The first hour, written as a path: what to do, in what order, and what “done” looks like at each step. It is the page that decides whether a trial turns into a customer.

  • Create your account
  • Connect your first source
  • Send a test request

• Someone with a job to finish

  Guides

  One task per page, titled the way a person would ask for it. Not a tour of your menus. A route through the product to a specific outcome.

  • Invite your team
  • Set up single sign-on
  • Export your data

• A developer building against you

  Reference

  The exhaustive part: every endpoint, every parameter, every error, every limit. Nobody reads it start to finish, and everybody needs the one line that applies to them.

  • Endpoints
  • Parameters and types
  • Error catalogue
  • Rate limits

• Someone who is already stuck

  Troubleshooting

  The errors people actually hit, titled with the message they are staring at, so searching the exact text lands on the fix rather than on a forum thread.

  • 401 invalid_token
  • Webhook fired twice
  • Import stops at 10,000 rows

The ideas that matter

Eight things worth understanding

1. 01

   What actually counts as documentation?

   Anything that answers a question about your product in writing, on a page a person can link to. If a customer or a developer can ask it, there should be a page that answers it. Most companies already have the knowledge. It is sitting in support replies, Slack threads and people’s heads, being explained again every week.

   A written answer is read hundreds of times. A support reply is read once.

2. 02

   Why does structure matter more than volume?

   A long, unstructured page hides the answer as effectively as having no page at all, because search returns the document rather than the paragraph the reader needed. Structure is what makes a set usable: one question per heading, predictable navigation, and pages small enough that a link points at an answer instead of a chapter.

   Having docs is not the goal. Being able to find the answer inside them is.

3. 03

   What is information architecture?

   The map: which pages exist, how they are grouped, and what a reader sees first. It is decided before anything is written, because the order pages appear in is itself an answer. It tells a newcomer what matters and in what sequence. Getting this wrong is the most common reason documentation feels bad despite being accurate.

   If two people would file the same page in two different places, the map is not finished.

4. 04

   What does docs-as-code mean?

   Treating documentation like software: the pages live in a repository, changes arrive as pull requests, and a build publishes them. That buys you review, history, and the ability to fail a build when a link breaks or a code sample stops compiling. The same guarantees you already expect from your application code.

   It also means docs can ship in the same commit as the change they describe.

5. 05

   Why do AI assistants change what good docs look like?

   Assistants answer questions about your product by reading whatever is public, and your documentation is the source they quote. When a page is clear, current and structured, an assistant cites it. When it is thin or contradictory, the assistant fills the gap by guessing. And the guess is repeated to your customers in your name.

   A wrong AI answer about your product is still your support ticket.

6. 06

   What is llms.txt?

   A plain-text file at the root of a site that lists its important pages and what each one contains, so a model reading the site has a map rather than a crawl. It is a convention rather than a standard, it costs almost nothing to publish, and it makes the difference between an assistant finding your reference and finding a marketing page.

   Same idea as robots.txt or a sitemap, aimed at a different kind of reader.

7. 07

   How do you know whether documentation is working?

   By what stops happening. The same question stops arriving in support. Trials stop stalling at the same step. Developers stop opening tickets that a page already answers. Page views tell you what was opened; the support queue tells you what was actually resolved.

   The best measure of a page is a question that no longer gets asked.

8. 08

   Who should write it?

   Someone who can read the code and sit with the support queue, and who is not the person who built the feature, authors of a thing are the worst judges of what is obvious about it. Engineers should confirm facts, not draft pages; that is the split that survives a busy release week.

   The bottleneck is rarely writing. It is deciding what is worth writing.

Glossary

The words people use

API reference

The exhaustive description of every endpoint, parameter and error, generated or hand-written, but always complete.

OpenAPI

A machine-readable description of a REST API. A reference can be generated from it, and drift between the two can be detected automatically.

Information architecture

The structure of the documentation set: what pages exist and how they are grouped.

Docs-as-code

Documentation kept in version control and published by a build, reviewed the same way code is.

Single-sourcing

Writing a fact once and reusing it everywhere it appears, so it can only be wrong in one place.

Changelog

A dated record of what shipped, written for the people using the product rather than the people who built it.

llms.txt

A root-level text file listing a site's key pages so AI assistants can read it as a map instead of crawling blindly.

Ask AI

Search over your own documentation that answers in prose and cites the page it came from.

Style guide

The agreed rules for voice, terminology and formatting, so pages by different authors read as one product.

Content audit

A pass over what already exists to find what is wrong, duplicated, or missing before anything new is written.