> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synscribe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# What Makes a Good Documentation Page

> Evaluate whether people and AI agents can find and use a documentation page, then choose the page archetype and next improvement it needs.

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](/theory/documentation-site/optimize-documentation-pages-for-seo-geo),
because it answers the immediate question “How should I improve this page for discovery?”

## Good documentation can reduce support friction and increase discovery

| Organizational purpose              | Audience behavior that creates it                              | Example measures                                                     |
| ----------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------- |
| Reduce support load and frustration | Users find and complete the correct answer without escalation  | Repeated ticket rate, time to first success, error recurrence        |
| Increase qualified leads and users  | Searchers or agents discover, evaluate, and select the product | Non-brand impressions, qualified visits, citations, trials, sign-ups |

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.

| Archetype           | Question it owns                              | A good page includes                                                        | Common bad version                                       | Published examples                                                                                                                                                                                                                                                                                                                                            |
| ------------------- | --------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Quickstart          | How do I reach first success?                 | One recommended path, prerequisites, action, output, first recovery         | Screenshot tour with several possible next steps         | [Anthropic, Get started with Claude](https://platform.claude.com/docs/en/get-started) · [Twilio, SMS developer quickstart](https://www.twilio.com/docs/messaging/quickstart) · [Resend, Send emails with Node.js](https://resend.com/docs/send-with-nodejs)                                                                                                   |
| How-to guide        | How do I complete one task?                   | Complete sequence, realistic input, expected result, important failure      | Partial example assembled from several pages             | [Bun, Write a simple HTTP server](https://bun.com/docs/guides/http/simple) · [GitHub, Adding a new SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) · [Google, Block Search indexing with `noindex`](https://developers.google.com/search/docs/crawling-indexing/block-indexing) |
| Integration guide   | How do I make two products work together?     | Least-privilege setup, both sides of configuration, end-to-end verification | Credential setup that never demonstrates the integration | [Slack, Sending messages using incoming webhooks](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/) · [GitHub, Configuring OpenID Connect in AWS](https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws) · [Attio, Attio MCP](https://docs.attio.com/mcp/overview)                    |
| Concept or decision | What should I choose, and why?                | Default when one exists, decision criteria, limits, implementation links    | Option descriptions with no recommendation               | [Next.js, Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components) · [React, You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect) · [Cloudflare, Choose a data or storage product](https://developers.cloudflare.com/workers/platform/storage-options/)                         |
| Reference           | What is the exact contract?                   | Stable names, types, fields, auth, response, limits, errors, lifecycle      | Huge schema with no path into common operations          | [Stripe, Create a PaymentIntent](https://docs.stripe.com/api/payment_intents/create) · [MDN, 404 Not Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/404) · [PostgreSQL, SELECT](https://www.postgresql.org/docs/current/sql-select.html)                                                                                           |
| Exact error         | What does this exact code or message mean?    | Payload, cause-separating checks, fixes, retry safety, operation link       | Giant alphabetical error table                           | [Stripe, Decline codes](https://docs.stripe.com/declines/codes) · [Rust, Error code E0382](https://doc.rust-lang.org/error_codes/E0382.html) · [Next.js, Text content does not match server-rendered HTML](https://nextjs.org/docs/messages/react-hydration-error)                                                                                            |
| Troubleshooting     | Why do I observe this symptom?                | Symptom-first branches, discriminating tests, result-specific next steps    | “Check your configuration and contact support”           | [Kubernetes, Debug Pods](https://kubernetes.io/docs/tasks/debug/debug-application/debug-pods/) · [Google, Page indexing report](https://support.google.com/webmasters/answer/7440203) · [Docker, Troubleshoot topics for Docker Desktop](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/)                                       |
| Evaluation or trust | Is this product suitable for my requirements? | Scoped claim, inclusions, exclusions, evidence, limits, decision path       | Unsupported “secure” or “enterprise-ready” claims        | [Supabase, HIPAA Compliance and Supabase](https://supabase.com/docs/guides/security/hipaa-compliance) · [Notion, Security practices](https://www.notion.com/help/security-and-privacy) · [Stripe, Security at Stripe](https://docs.stripe.com/security)                                                                                                       |

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.

| Failure you observe                                  | Continue to                                                                                                         |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Generic title, weak opening, vague headings          | [Optimize documentation pages for SEO and GEO](/theory/documentation-site/optimize-documentation-pages-for-seo-geo) |
| Unknown questions, wording, or page priorities       | [Research documentation questions](/theory/documentation-site/research-documentation-questions)                     |
| Broken canonical, crawl, Markdown, or machine routes | [Build the technical foundation](/theory/documentation-site/technical-foundation)                                   |

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

Choose one documentation URL and complete:

```text theme={null}
Dominant question:
Audience:
Archetype:
Can a person find it? pass / fail / unknown
Can an agent find it? pass / fail / unknown
Can a person use it? pass / fail / unknown
Can an agent use it? pass / fail / unknown
Support outcome expected:
Growth outcome expected:
First blocking failure:
Next lesson:
```

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](/theory/documentation-site/optimize-documentation-pages-for-seo-geo).