Skip to content

Drafting spec — The Technical SEO Reference

Read this in full before drafting or reviewing any chapter. It is the binding contract for every file in technical-seo/.

Voice & register

Match ../seo-checklist.md: dense, declarative, evidence-first, zero filler. The book is a reference, not a checklist — write explanatory prose and structured sections, not checkbox lists. Every paragraph must either state a verified mechanism, correct a misconception, or tell the reader how to diagnose something. If a sentence does none of those, cut it. British/US spelling: US. No marketing tone, no "in today's fast-paced SEO landscape" filler — ever.

Provenance legend (tag every claim)

  • 🟢 Documented by the authoritative primary source — for Google behavior: an official Google source (docs, blogs, help center, and Google's own recorded channels — Search Central YouTube, official Search Off the Record transcripts — always date-stamped, e.g. "🟢 (recorded statement, office hours, May 2018)"). For third-party crawlers/products: that vendor's own official documentation, scoped to the vendor ("🟢 per OpenAI's bots page"). The quote must have been fetched live BY YOU during drafting. The research JSON is the map, not the evidence. ⚠️ Third-party measurements/studies (MERJ/Vercel, CrUX analyses by others) are never 🟢 — they are ⚪ with the primary link, framed as measurement not doctrine.
  • 🟡 Google-backed in spirit / informal — Google supports the principle but specifics are house standards; OR an informal Googler statement (X post, podcast, office hours) — these MUST carry the person, venue, year, and (if secondary) the secondary source: e.g. "🟡 (Illyes via Search Off the Record, 2023, per SEJ writeup — primary unavailable)".
  • ⚪ Industry practice — sensible, widely used, Google is silent. Never citable as "Google says."
  • 📘 Standard — defined by a web standard (RFC 9309, RFC 3986, BCP 47, sitemaps.org, WHATWG, schema.org, OGP). When Google's implementation differs from the standard, say so explicitly and tag each side.
  • ⚠️ — a trap, correction, or deprecation. Use for anything practitioners commonly get wrong.

Hard rules

  1. Live-fetch rule (V1): every 🟢 quote in your chapter must come from a page you fetched during drafting. Load WebFetch via ToolSearch("select:WebFetch,WebSearch"). If a fetch fails or wording differs from the research JSON, the LIVE page wins — and note the discrepancy in your return summary.
  2. V0 verdicts are binding: read ../research/v0-verification.json before drafting. If a verdict touches your chapter, follow it (e.g., a quote demoted to 🟡-informal stays demoted).
  3. Canonical-home rule: each shared topic lives in ONE chapter; everyone else cross-references with "→ Ch N §x". Assignments:
  4. robots.txt syntax/semantics → Ch 3 (Ch 2/5/7 reference it)
  5. HTTP status handling by Google → Ch 2
  6. the 2MB/64MB fetch limits → Ch 2
  7. noindex-requires-crawlability + long-term-noindex→nofollow → Ch 7
  8. snippet controls inventory & AI-surface scope → Ch 7 (Ch 5 covers only the AI-policy decision layer; Ch 14 only image-specific interplay)
  9. WAF/challenge-page/CDN failure modes → Ch 4
  10. redirect type taxonomy → Ch 16 (Ch 8 covers only redirect-as-canonical-signal)
  11. hreflang spec → Ch 11
  12. Page indexing status taxonomy → Ch 7; the "currently not indexed" diagnosis playbook → Ch 21
  13. news-surface eligibility (Top Stories/News tab/news.google.com) → Ch 14 (Ch 9 covers only news-sitemap format)
  14. title-link/snippet/date generation → Ch 13 (Ch 12/14 cross-reference)
  15. GSC platform properties (Jul 2026) → Ch 19
  16. No invented facts. If the research JSON asserts something you cannot verify live and no V0 verdict covers it, either label it honestly (🟡/⚪ with source) or put it in your "unverified — for V2" return list. Never silently promote.
  17. Dates matter. State effective dates for every deprecation/change. FAQ rich results: effective May 7, 2026 (docs removed Jun 15) — not "June 2026."
  18. Citations file: alongside your chapter, Write ../research/citations/chNN.json: [{"url","title","fetch_date","last_updated_shown","quotes_used":[...]}] for every source you fetched. Appendix C compiles these.

Chapter template

# Ch N — Title
*Part X — Part name · The Technical SEO Reference*

> **Playbook coupling:** `seo-checklist.md` covers this in N lines (Phase X, lines a–b): <one-sentence summary>. This chapter adds: <what>.

<1-paragraph chapter thesis: the mental model for this domain.>

## N.1 <Section>
<prose + tagged claims + exact quotes with inline links>

…

## Symptoms & diagnosis
| Symptom | Likely cause | Where |
|---|---|---|
(chapter-closing table; these rows feed Ch 21's master index)

## Sources
<bulleted list: title — URL (fetched 2026-08-XX; page last-updated YYYY-MM-DD if shown)>

File naming

02-crawling-infrastructure.md, 03-robots-txt.md, 04-hosting-cdn-waf-dns.md, 05-ai-crawlers-bot-management.md, 06-rendering-javascript.md, 07-indexing-controls.md, 08-canonicalization.md, 09-sitemaps-discovery.md, 10-urls-architecture-navigation.md, 11-international.md, 12-structured-data.md, 13-display-layer.md, 14-media.md, 15-performance-page-experience.md, 16-redirects-migrations.md, 17-security-incidents.md, 18-spam-enforcement.md, 19-search-console.md, 20-operations.md, 21-diagnosis.md, 01-foundations.md, 00-index.md, appendix-{a,b,c,d}-*.md.

Length

300–600 lines per chapter. Below 300 usually means mechanics are missing; above 600 usually means you're duplicating another chapter's home topic or padding.

Cross-references

Format: → Ch 8 §8.3 (em-style arrow, chapter number, section). To the playbook: → playbook Phase 1, "Canonicalization & duplication".