docs-deploy-readiness

Docs Deploy Readiness

Overview

Judge whether a docs/content site can be deployed publicly today. Discover the site's own stack, inventory, and page template first; only then apply the universal bar — never import another project's checklist wholesale.

This skill audits the DOCS about a thing. Whether the thing itself is shippable is handoff-readiness.

When to use / when NOT

Use when:

• A docs or content site is about to go public (first deploy, big relaunch, domain move).
• Someone asks "is the docs site done?", "audit the docs", "what's missing before launch?".
• Docs were generated/written in bulk and nobody has verified them against the code.

Do NOT use for:

• Auditing the library/CLI/app itself → handoff-readiness.
• Rewriting prose → humanizer / humanize-readme (this skill only FLAGS prose).
• A README in a repo root (no deploy target) → humanize-readme.
• Runtime security of a server backing the docs → security-surface-audit.

How it works

Step 1 — DETECT the stack and deploy target

Read before judging. Establish, with file evidence:

1. Framework + render mode: static SSG, SSR, hybrid prerender? Check package.json scripts, framework config (vite.config.*, next.config.*, astro.config.*, docusaurus.config.*, or equivalent), Dockerfile, CI deploy workflow.
2. Build command and output: what command produces the deployable artifact, and what is it (a dist/ of HTML? a Node server entry?).
3. Origin and environment: what canonical URL/base path does the site assume? Which env vars are baked at build time vs read at runtime? Non-root hosting (e.g. /docs/) needs explicit base config.
4. Content source: where do pages live (MDX dir, CMS, generated reference), and is any of it generated — if so, is the generator part of the build?

Step 2 — DETECT the inventory (should-exist vs exists)

Build the definitive list of what SHOULD be documented from the source of truth, not from the docs:

• Library: public exports map / index entry / per-item registry index.
• CLI: every command and flag in the command definitions or --help output.
• API/server: the route table.
• Config: the schema or parser that consumes config/env vars.

Then list the pages that exist (rg --files over the content dir, or the route manifest). Diff the two lists both directions. (Illustrative example: a shadcn-style registry's registry.json items vs docs/content/components/*.mdx — use the project's actual equivalent.)

Step 3 — DETECT the project's own page template

Sample the 3–5 most complete pages of each page type. Derive the section skeleton this project itself uses (e.g. preview → install → usage → API table → accessibility). That skeleton — not an imported ideal — is the consistency bar for siblings.

Step 4 — APPLY the five bars

Run the checks in Quality bar below. For each finding record: page/file path, bar (coverage/anatomy/prose/accuracy/deployability), severity (blocker/warning/nit), and the fix.

Step 5 — Verify the build cold

Build in a clean environment (fresh install; in a container if the deploy target is Docker). Prerendering that works on the dev machine and fails in CI/container is a known failure class. Confirm the output contains no dev origins (localhost URLs, dev tokens) and that all internal links/anchors resolve in the built output.

Step 6 — Score and report

Emit the scorecard in Output. For large sites, fan the per-bar checks out to parallel agents via convergence-loop and merge into one scorecard.

Quality bar

(a) Coverage

Check	Pass condition
Every public/visible item has a page	Inventory diff (Step 2) is empty, or every gap is justified in writing
No stub pages on critical paths	No page that is a heading + one sentence; no "Coming soon" reachable from nav
No orphan pages	Every page reachable from nav/search; no dead routes in the manifest
Getting-started path complete	A new user can go from landing → install → first success without a gap

(b) Page anatomy

Check	Pass condition
Template consistency	Every page of a type has the sections its siblings have (skeleton from Step 3)
Live/working examples	Examples render or are verified to compile; more than one usage shape where the project's template shows several
Every consumption path covered	If the thing installs N ways (e.g. CLI add, manual copy, npm), each page documents all N
Reference tables complete	API/props/flags/options tables list type + default for every entry
A11y/keyboard notes	Present where siblings have them; interactive components document keyboard behavior

(c) Prose quality

• SCAN for AI-writing tells (list in the 2026 snapshot below) with rg over the content dir; flag pages, count hits per page.
• Flag broken English, tense drift, and inconsistent terminology for the same concept.
• Defer the rewrite to humanizer (general prose) / humanize-readme (README-shaped pages). Do not rewrite inside this audit.

(d) Accuracy vs code

Check	Method
Documented-but-nonexistent	Every flag, option, env var, route, prop, default named in reference pages → grep the source; flag misses
Exists-but-undocumented	Reverse direction from the Step 2 inventory
Defaults and types match	Compare documented defaults against the actual schema/parser values
Privacy/security claims true	"Runs locally", "never sends data", "no telemetry" → verify against actual network/telemetry code paths; a false claim here is an automatic blocker
Snippets current	Imports, package names, and commands in snippets match today's source

(e) Deployability

Check	Pass condition
Per-page meta	Unique <title> + meta description on every page
Social meta	OG + Twitter card tags; image resolves on the production origin
Canonical URLs	Absolute, correct production origin, no localhost
sitemap.xml + robots.txt	Sitemap covers all public routes; robots references it; prerendered routes match
404 page	Branded, with navigation/search escape — not the host default
Search	Works on built output; zero-result state handled
llms.txt	Present for developer-tool docs (see snapshot); llms-full.txt where siblings in the ecosystem ship it
Clean build	Step 5 passed: fresh-environment build + prerender succeed, links resolve

Quality bar (2026 snapshot)

Distilled 2026-06-10 from researched norms (quality-bar.md, sections 6–7 + deploy gotchas). Refresh via WebSearch if executing after ~mid-2027; treat as the floor, not the ceiling.

• Per-component docs page anatomy (norm set by Radix / Base UI / React Aria / shadcn docs): live rendered preview with copyable source toggle; installation per consumption path (CLI incl. namespaced registry, manual copy with file list, npm import); API reference table per part (props, types, defaults, data-attributes, CSS variables); an Accessibility section with a keyboard-interaction table mapped to the matching WAI-ARIA APG pattern; multiple usage examples (controlled, uncontrolled, composed, form integration). (These named projects are the reference points, not required tech.)
• IA: Diátaxis (tutorials / how-to / reference / explanation, https://diataxis.fr/) is the cited structure for library docs; component pages = reference + examples, getting-started = tutorial.
• Search is table stakes — Cmd+K palette over docs content.
• llms.txt is near-default for developer-tool docs (platforms like Mintlify, Fern, GitBook, Vercel ship it automatically; IDE/agent tools fetch it, AI crawlers mostly ignore it and crawl HTML). llms-full.txt and per-page markdown routes are the common companions.
• Registry/ecosystem affordances where applicable: one-command installs per item and "Open in …" buttons are 2025–2026 ecosystem conventions (illustrative — only for registry-style products).
• Deploy gotchas observed in the wild: prerendering can fail inside Docker builds despite passing locally; client env vars are inlined at build time while server env is runtime; non-root hosting needs explicit base-path config; sitemap generation is usually NOT built into the framework — verify it actually exists in the output.
• Writing-quality tells to scan for (from Wikipedia "Signs of AI writing"): inflated significance ("pivotal", "stands as a testament"); negative parallelism ("not just X, but Y"); rule-of-three triads everywhere; vague attribution ("widely regarded"); promotional adjectives ("powerful", "seamless", "robust", "comprehensive", "blazing-fast"); trailing "-ing" impact claims ("…, ensuring accessibility"); AI vocabulary ("delve", "leverage", "crucial", "streamline", "landscape"); copula avoidance ("serves as", "boasts" for plain "is/has"); em-dash and boldface overuse; bolded-header inline lists as default prose; formulaic wrap-ups ("In conclusion"); elegant variation (component → element → widget for the same noun). Good reference prose: short declarative sentences, concrete facts, imperative voice for instructions, no marketing register.

Output

Produce exactly this report:

# Docs Deploy Readiness — <site name> @ <commit/date>

Stack: <framework, render mode, build command, output, deploy target>
Inventory: <N items should be documented / M pages exist>

Verdict: READY | READY WITH WARNINGS | NOT READY

| Bar           | Score /10 | Summary                          |
|---------------|-----------|----------------------------------|
| Coverage      | n         | <one line>                       |
| Anatomy       | n         | <one line>                       |
| Prose         | n         | <one line>                       |
| Accuracy      | n         | <one line>                       |
| Deployability | n         | <one line>                       |

## Blockers (deploy stops here)
- B1 [accuracy] <page path> — <issue> — <fix>
- B2 [deployability] ...

## Warnings (ship-with, fix soon)
- W1 [anatomy] <page path> — <missing section siblings have>

## Coverage gap list
| Item | Source location | Page | Status |
|------|-----------------|------|--------|
| <public item> | <file:line> | — | MISSING |
| <page> | — | <path> | STUB / ORPHAN |

## Prose flags (defer rewrite to humanizer / humanize-readme)
| Page | Tell count | Worst tells |

Scoring: any blocker in accuracy or deployability ⇒ NOT READY. Empty blocker list + warnings only ⇒ READY WITH WARNINGS. Score each bar 0–10 on evidence, not vibes.

Common mistakes

1. Auditing only the pages that exist. The biggest gaps are items with no page at all — build the should-exist inventory from source of truth FIRST (Step 2).
2. Importing another stack's checklist. Don't demand a registry install tab on CLI docs, or an APG keyboard table on a config-reference page. The bar is the project's own template plus the universal checks.
3. Trusting the docs about the code. Every reference claim gets grepped against source. Privacy/security claims especially — a docs page saying "no data leaves your machine" over code that phones home is the worst possible finding to miss.
4. Rewriting prose mid-audit. Flag and defer to humanizer / humanize-readme; rewriting burns the audit's scope and context.
5. Verifying the build only on the dev machine. Clean environment, fresh install, container if that's the target. Prerender-in-container failures are common and invisible locally.
6. Treating dead links/anchors and stub pages as nits. On a critical path (getting started, install) they are blockers.
7. Forgetting docs chrome accessibility. Nav, search palette, theme toggle, and code-copy buttons are product UI — hand them to accessibility-compliance, don't skip them because "it's just docs".
8. Skipping jargon review. Public docs leaking internal codenames or pre-rename terms is a launch embarrassment — run jargon-leak alongside this audit.