Documentation SEO: Checklist, Template and Tested Example

By Abiot Y. Derbie - Founder, RankEcho - Updated 2026-09-12

# SaaS documentation-page review brief

Version 1.0 — manual review brief

## Task control
- One public reader goal, governing source, owner, and canonical URL [required]:
- Public/private eligibility and access boundary [required]:
- Supported version, prerequisites, role, permission, object, or ID [required]:
- Last verified date, review cadence, and update triggers [required]:

## Completion contract
- What the task reads or changes, including side effects:
- Exact request, interface action, or ordered steps; inputs, headers, and safe placeholders:
- Expected status, response, state, and success check:
- Failure signals, corrections, and escalation owner:
- Security, privacy, plan, rate, region, and version limits:
- Setup, reference, version, troubleshooting, support, and honest product links:

## Manual review
- Map eligibility, prerequisites, steps, result, errors, recovery, and next action to visible answer locations.
- Verify product facts with their owners. Inspect initial HTML and a browser.
- Where authorized, test the real task with safe non-production data; record request, response, side effects, cleanup, and unresolved cases.
- Ask a representative reader to attempt it. Inspect indexing and query data separately.

## Proposed measurement
- Discovery: eligible impressions and clicks; separately identified AI-referral sessions.
- Completion: defined task starts, validations, recoveries, support escalations, and product actions already observable.
- Keep search, referral, session, action, account, and customer denominators separate; preserve unknown attribution and avoid causal claims.

## Filled locally tested fictional example: HarborDesk
- Goal, source, owner: read an existing export's status from a fictional API v1 task specification; proposed owner is the API documentation team.
- URL and eligibility: https://harbordesk.example/docs/v1/read-export-status is a public-task placeholder with no working API. Real tokens, account data, and restricted instructions stay private.
- Version and access: API v1, exports:read, existing ID exp_demo, and the fixed fictional-read-token accepted locally. This is not a real OAuth or scope test.
- Request description: GET /v1/exports/exp_demo with Authorization: Bearer fictional-read-token. It reads status and creates, exports, or downloads nothing. Do not send it to the example domain.
- Expected result: 200 {"id":"exp_demo","status":"ready","row_count":12}.
- Failures: missing token → 401 {"error":"invalid_token"}; wrong token → 401 {"error":"invalid_token"}; exp_missing with the fixed token → 404 {"error":"export_not_found"}.
- Before: 200 HTML at the same URL with the same title, canonical, and robots value; decisive facts were only in script[type=application/json]. Answer checks found 0 of 4.
- After: 200 HTML with #prerequisites, #request, #response, and #errors sections plus a[href] navigation. Answer checks found 4 of 4.
- Exact request receipt: success / missing token / wrong token / missing ID → 200/401/401/404.
- Update triggers: version, permission, endpoint, header, response, status, error, owner, URL, or access-policy changes.
- Proposed measurement: task-URL impressions and clicks, separately identified AI referrals, status-check starts and successes, recoveries, and support escalations where defined.
- Unperformed: browser, real API, provider/canonical, user-completion, site-search, indexing, query-performance, and product-action tests.

Which documentation task should own the page?

Choose one observable reader goal with a starting state, safe action, result, and recovery. Diátaxis describes how-to guidance as practical direction toward a concrete goal; link reference and explanation when they answer different questions.

Check whether another page already finishes the task. Keep product value, pair compatibility, field definitions, and broad error classes with their owners, then connect them in the reader's order of work.

Where should each developer answer appear?

Lead with who can do the task, its version and prerequisites, what changes, and what success looks like. Put the complete steps, result, failures, recovery, and next link under descriptive headings instead of hiding a required permission in a sample.

Map each material question to a visible location and governing source. GitHub's public get-a-repository page separately presents permissions, parameters, statuses, and samples. We reviewed its organization only and did not test that endpoint.

What did the local HarborDesk test establish?

HarborDesk is a fictional in-memory API and HTML app tested locally on September 12, 2026. It used no network, account, or external data. Its fixed task reads an existing API v1 export status with ID exp_demo. The exports:read permission label is instructional; the local app accepts one fixed placeholder token and does not implement or validate real scopes.

Before excerpt: “Use this guide to check an existing export.” Decisive facts were only in script[type=application/json]. After excerpt: “Check an existing HarborDesk export using a read-only API v1 request. This fictional request does not create an export.” Four normal initial-HTML sections and direct a[href] links then exposed the answers.

Scope: the check removed scripts, matched fixed strings in named source sections, and exercised four local API rules. It did not run a browser or JavaScript, test a real API or user, or measure site search, indexing, rankings, citations, traffic, or cause. Its 401 and 404 rules are example-specific.

How do you write a request, result, and recovery without creating risk?

State whether the action reads or changes data before its code block. Label placeholders, replaceable values, side effects, safe test conditions, cleanup, and the permission owner. Keep secrets and account-specific examples out of public pages.

HarborDesk's instructional GET returns {"id":"exp_demo","status":"ready","row_count":12} and changes nothing. Its domain has no working API. A real owner must validate authentication, response, failures, and side effects in an authorized environment.

For recovery, state the observed signal, documented cause, correction, and escalation route. Preserve unknown cases, and do not turn this example's 401 or 404 behavior into a universal rule.

How should public delivery and internal links support discovery?

Use a descriptive title and URL, reader vocabulary, clear navigation, and text alternatives for meaningful media, as the reviewed Read the Docs guide recommends. Keep decisive task facts in normal text. Google can run JavaScript, but describes crawl, render, and index phases and says server-side or pre-rendering still helps because other bots may not execute it.

Use descriptive a[href] links to setup, reference, errors, versions, and support. Link the paired-capture diagnosis and Next.js repair when those tests establish a delivery problem; an initial-source miss alone is insufficient.

Google says AI search features use ordinary Search eligibility and need no special AI file or schema. Important facts should be text, with applicable structured data matching them. These practices do not promise indexing, appearance, ranking, traffic, or action.

What should you do with duplicate tasks and supported versions?

For duplicate or very similar URLs, Google recommends aligning redirects, sitemaps, internal links, and rel=canonical, while retaining the final canonical choice. Do not use noindex to force it.

Give materially different supported versions their own owner and navigation. Consolidate truly equivalent routes deliberately. Keep private documentation within its access boundary.

How do owners validate and measure the page?

Have documentation, product, engineering, security, support, and version owners verify their facts. Inspect initial HTML and a browser, run an authorized non-production task test where possible, and record the request, response, side effects, cleanup, unresolved cases, approver, and review date. Add a representative reader test.

Track eligible impressions and clicks, separately identified AI referrals, and defined task or support actions with separate denominators. Preserve unavailable and unattributed data; sequence does not establish cause.

Refresh when versions, permissions, inputs, responses, errors, access, canonicals, links, or owners change. Map users and supporting links before retiring a task.

Where does RankEcho fit after the review brief?

The brief works without an account. The paid Fix Engine organizes bounded changes for human review and manual shipment; it does not deploy code, run a documentation platform or live-API test, provide site search, or publish to a CMS. Full-page writing is a separate paid content add-on.

Free audits check Perplexity and Gemini once per prompt. Paid and trialing accounts add ChatGPT, Claude, and Google AI Overviews when configured for the account, for up to 5 engines. RankEcho does not currently run Microsoft Copilot checks. RankEcho does not guarantee rankings, citations, traffic, or conversions.

Frequently asked questions

Sources reviewed

Material technical claims below were checked against primary provider documentation. The sources support the documented control or signal, not a guarantee of indexing, ranking, an AI impression, or a citation.