# Docs Deploy Readiness

> Use when a documentation or content site needs a pre-deploy audit — someone asks "are the docs ready to ship", requests a docs review, coverage gap check, stub/orphan page hunt, docs-vs-code accuracy verification, SEO/meta/OG/canonical/sitemap/robots/llms.txt check, 404 or search validation, or a clean-environment docs build check before going public. Any stack (SSG, SSR, MDX, static export). For the artifact being documented, use handoff-readiness instead.

- Skill: `b4r7x/docs-deploy-readiness` (Agent Skill)
- Install (CLI): `npx skillmds@latest add b4r7x/docs-deploy-readiness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/b4r7x/docs-deploy-readiness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: b4r7x (https://skillmd.com/u/b4r7x)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/b4r7x/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:

```markdown
# 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.