docs: deepen system design fieldbook - #89
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
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 --checkactionlintpython3 scripts/validate_docs.py— 160 articles per languagenpm run docs:build— production VitePress build passespython3 scripts/validate_built_site.py— 323 HTML pages, 73 pages with rendered math; no broken generated page/anchor links or MathJax error nodes