Skip to content

docs: deepen system design fieldbook - #89

Merged
babushkai merged 5 commits into
mainfrom
docs/book-depth-remediation
Jul 31, 2026
Merged

docs: deepen system design fieldbook#89
babushkai merged 5 commits into
mainfrom
docs/book-depth-remediation

Conversation

@babushkai

Copy link
Copy Markdown
Owner

Summary

  • Consolidate nine overlapping chapter routes into their canonical owners, reducing the English book from 169 to 160 distinct articles while preserving English/Japanese path parity.
  • Rewrite the weak core, scaling, storage, messaging, operations, workflow, case-study, whitepaper, and engineering-platform material around explicit contracts, invariants, protocols, quantitative models, failure traces, evolution, and verification.
  • Deepen the ML/LLM boundary chapters for evaluation, monitoring, RAG, inference infrastructure, harnesses, GPU internals, and capacity economics.
  • Replace repeated production-checklist boilerplate with chapter-specific decision frameworks and evidence scope.
  • Repair MathJax/Pandoc syntax, currency collisions with dollar-math delimiters, sidebar/book manifests, localized links, and generated anchors.
  • Add source- and rendered-site quality gates for corpus parity, manifest completeness, duplicate prose/headings/titles, portable math, MathJax errors, and generated page/anchor integrity.
  • Run the PDF/EPUB workflow on pull requests so LaTeX regressions are caught before merge.

Why

The book had multiple sections that owned the same mechanism, repeated generic production advice, and mixed tutorial snippets with unsourced claims. That made it read like an accumulated draft rather than a coherent system-design fieldbook. The previous source-only checks also allowed malformed math and broken rendered anchors to reach the site.

This change gives each mechanism one canonical owner, makes cross-chapter boundaries explicit, and turns the editorial standards into automated gates.

Reader impact

Readers get a curated 160-chapter English fieldbook with substantially deeper production reasoning and fewer duplicate routes. Japanese routes remain structurally aligned, and affected localized links and rendering issues are repaired.

Validation

  • git diff --check
  • actionlint
  • python3 scripts/validate_docs.py — 160 articles per language
  • npm run docs:build — production VitePress build passes
  • python3 scripts/validate_built_site.py — 323 HTML pages, 73 pages with rendered math; no broken generated page/anchor links or MathJax error nodes

@babushkai
babushkai marked this pull request as ready for review July 19, 2026 20:45
RFC 9333 is Minimal IP ESP, not the RateLimit fields spec. The RateLimit
header fields document is still an active Internet-Draft
(draft-ietf-httpapi-ratelimit-headers), so cite the datatracker entry.
@babushkai
babushkai merged commit 9d67d99 into main Jul 31, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant