Skip to main content
A good documentation page answers one dominant question, is easy to identify before selection, and lets a person or AI agent complete or verify the answer after selection. Its title, URL, description, opening, and headings make the promise clear; its procedure, evidence, limits, and recovery path keep that promise. Evaluate the page with four separate checks: can a person find it, can an agent find it, can a person use it, and can an agent use it? A failure in any one check identifies the next improvement rather than producing a vague instruction to “rewrite everything.”

​
Evaluate documentation with four find-and-use checks

By the end of this lesson, you should be able to:
  • separate a page’s discovery job from its usage job;
  • connect both jobs to an organizational outcome;
  • identify the page archetype a question requires;
  • recognize when a page has the right information but the wrong shape;
  • choose the next course lesson from the page’s failure mode.

​
A good documentation page must be findable and usable

​
Can a person or AI agent use the documentation answer?

The selected page must supply enough information to complete, verify, or correctly explain the task. Depending on the question, that may require prerequisites, code, a decision table, expected output, limits, and a recovery path. Use fails when the page:
  • sends the reader through several pages to assemble one answer;
  • hides essential instructions in screenshots or interactive components;
  • provides a request without the expected result;
  • describes options without helping the reader choose;
  • lists errors without distinguishing their causes;
  • states a product claim without scope or evidence.

​
Can a person or AI agent find the right documentation page?

The right page must be identifiable before someone reads the complete answer. Its title, description, H1, opening, headings, URL, internal links, and machine representations should agree on one job. Find fails when the page:
  • uses a generic label such as Overview, Usage, or Method 3;
  • depends on sidebar context to name the product or task;
  • buries a high-intent operation as an anchor inside a huge reference;
  • exposes different page identities in HTML and Markdown;
  • competes with another page for the same question;
  • cannot be crawled, indexed, or selected from its metadata and opening.
The course deliberately teaches this second purpose first in Optimize Documentation Pages for SEO, GEO, and Agent Discovery, because it answers the immediate question “How should I improve this page for discovery?”

​
Good documentation can reduce support friction and increase discovery

These are outcome hypotheses, not automatic results. A technically crawlable page does not guarantee leads, and fewer tickets can also mean fewer users. Establish a baseline and measure the full path.

​
Choose the page archetype from the question

An archetype is the shape of answer the question requires. It is not a mandatory content quota. The same product may need all eight shapes, but only when real questions justify them.

​
What the published examples demonstrate

These pages were read on 12 August 2026 and selected for doing one archetype’s job well, not for being flawless. Each is worth opening for one specific move:
  • Quickstart: Anthropic states prerequisites, gives one linear path per language, prints the actual JSON response, and ends with a single next step. Twilio supplies a virtual phone so first success is observable without a second device, and routes no-code readers away in its opening paragraph.
  • How-to: Bun’s title is the query and the page owns exactly one outcome. GitHub handles macOS, Windows, Linux, and the CLI as variants inside one page instead of forking it. Google states the caveat that silently breaks the task—noindex fails if robots.txt blocks the page—before the instructions rather than after them.
  • Integration: Slack configures both the app side and the caller side, names the incoming-webhook scope, and proves the link with an observable result in a channel.
  • Concept or decision: Next.js and React both state the default in the first paragraph, then explain when to depart from it. Cloudflare’s comparison table is indexed by the reader’s use case rather than by product name.
  • Reference: MDN and PostgreSQL repeat one strict template across an entire corpus, so a reader who has seen one page can predict every neighbouring page and guess its URL.
  • Exact error: Stripe states whether a retry is safe for each code. Next.js uses the literal error string as the title, so a pasted message finds its owner page.
  • Troubleshooting: Kubernetes writes its headings in the reader’s voice—My pod stays pending, My pod is crashing or otherwise unhealthy—which is the most copyable move in this table.
  • Evaluation or trust: Supabase leads with what the customer must do and states the exclusion outright (self-hosted deployments are not covered). Notion proves the archetype is not developer-only: it is a help-center page that satisfies a procurement reviewer.
Archetype quality is a property of a page, not of a company. Stripe has one of the strongest references and error tables here, while docs.stripe.com/payments/quickstart resolves to a page interleaving eight server languages with no single recommended path. Diagnose the page in front of you against the archetype its question demands.

​
Diagnose a page before rewriting it

Ask these questions in order:
  1. What question should this URL own? If that is unknown, do question research.
  2. Can the right audience find and identify it? If not, fix the discovery surface.
  3. Does its archetype match the question? If not, reshape or split the answer.
  4. Can a clean reader complete or verify it? If not, fix the body and examples.
  5. Can crawlers and agents receive the same answer? If not, fix technical delivery.
  6. Does the organization measure the intended outcome? If not, establish the baseline and owner.

​
Classify a documentation page by question, archetype, and failure

Choose one documentation URL and complete:
Do not average the four audience checks into one score. A dead canonical or unusable procedure is a blocker even when the writing is polished.

​
Definition of a well-classified documentation page

You have completed this lesson when you can name one dominant question and archetype for a real page, separate its find and use failures, and choose the next improvement lesson without falling back to “rewrite everything.” Continue to Optimize Documentation Pages for SEO, GEO, and Agent Discovery.