The documentation handbook
Everything else on this site answers how do I make Docsbook do X. This section answers the harder question underneath it: what is worth doing, and what makes it good.
It is the knowledge a documentation team accumulates over years — how a page has to be shaped before an answer engine can quote it, which number actually settles a question and which one only looks like it does, why a page that ranks can still be the wrong shape for the query, what to do in the week after a core update, and when an alert is worth installing versus when it becomes noise nobody reads by Thursday.
Two things make it usable rather than merely long:
- Every strong claim names its source. Where Google publishes something, we quote Google and link the page. Where a number comes from one practitioner's account, it is marked as one practitioner's account and you are told not to put it in a proposal. The whole registry is in Evidence.
- You can ask it instead of reading it. This corpus is what Docsbook's own assistant answers from. Ask it a question in the Ask AI box on any page of this site, or call
docsbook_assistantfrom an agent, and the answer comes back cited from the pages below. From an agent, passcontextalongside the question — your product, your audience, the intent the page has to answer — or you get this handbook's general answer rather than the one about your page.
The six sections#
what the page itself says: rules that catch errors while you write, writing for retrieval, presentation, and docs that ask for the sale.
deciding the page set before writing a page: which route you are on, what your reader is actually trying to do, and how to publish it.
reading the evidence: which metric settles what, the behavioural and content detectors, and how to tell whether the change you shipped worked.
the named readings an audit can take, from jobs-to-be-done to AI citation to market expansion, and the router that picks the two or three yours needs.
drift, monitors, events and CI checks: making the work keep happening without a person remembering to do it.
the sources and the graded claims. What is established, what is contested, what is merely repeated.
Where to start, by what you are doing#
| You are… | Start here |
|---|---|
| Writing documentation that does not exist yet | Which route are you on, then Deciding the page set |
| Improving pages that already exist | Writing rules, then Writing for retrieval |
| Trying to find out why traffic fell | Metrics without being confidently wrong, then Choosing a lens |
| Trying to get quoted by ChatGPT, Perplexity or AI Overviews | The GEO and AI-search lens, then Writing for retrieval |
| Tired of the docs going stale | Drift and Monitors and alerts |
| Deciding whether a tactic is worth a sprint | Claims — find it, read its standing |
What this handbook is not#
It is not Docsbook's product documentation. When a page here says a reading is worth taking, it links out to the product page that takes it — analytics, SEO, GEO, translations, the MCP server — rather than restating how the feature is configured.
It is also not neutral about its own limits. Several of the most-repeated claims in this field are, on inspection, one webinar deep. Those are marked hypothesis and carry a test you can run on your own site instead, because the number that survives a customer asking "says who?" is the one you measured yourself.