docs: book-not-blog organization, rage series plan with 6 posts

Content model inspired by makingsoftware.com:
- Topics not dates (grouped by investigation theme)
- Homepage as pitch not index (show quality before navigation)
- Series are first-class (landing pages, progress, cross-links)
- Figure density: 1 visual per 300-500 words for technical posts
- No blog chrome (no comments, shares, newsletter popups)

Rage series plan (6 posts, all sourced from kenotron-ms/rage):
1. Your Build Cache Is Lying to You (the stale cache problem)
2. Two-Phase Fingerprinting: BuildXL's Deep Magic (WF/SF algorithm)
3. Hooking Syscalls Without a Kernel Driver (3 OS, 3 mechanisms)
4. TypeScript 7 Makes the Build Harness More Important (counter-intuitive)
5. node_modules in a Content-Addressed Store (CI kill shot)
6. What I Learned Maintaining Lage and Why I Rewrote It (meta narrative)

Each post has planned visuals (diagrams, flows, animations via Remotion).

🤖 Generated with Amplifier

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
This commit is contained in:
Ken
2026-05-27 01:14:55 +00:00
parent d4a9f8b16f
commit adc487e63b
+44
View File
@@ -161,3 +161,47 @@ Visual check at blog.ampbox.io
v
Commit + push
```
## Content Organization: Book, Not Blog
The site is organized as a **book of investigations**, not a reverse-chronological
feed. Inspired by makingsoftware.com. Key principles:
**Topics, not dates.** Content is grouped by investigation theme (e.g., "Rage:
Rebuilding the Build System" is a 5-post series, not 5 unrelated entries). Dates
are secondary metadata, not the primary navigation.
**The homepage is a pitch, not an index.** Lead with a compelling excerpt, a
diagram, a question that creates intrigue. Show the reader what the content
quality is like before presenting any navigation. A flat list of article cards
is a cop-out. The homepage should make you curious.
**Series are first-class.** Multi-post series (like the Rage build system series)
get their own landing page with a visual overview, progress indication, and
cross-links between posts. Individual posts link to their series context.
**Figure density matters.** Target 1 visual per 300-500 words for technical posts.
Not decoration, but content: architecture diagrams, flow charts, before/after
comparisons, concept illustrations. If 500+ words pass without a visual, ask
what would replace them.
**No blog chrome.** No comments, no share buttons, no "related posts" sidebar,
no newsletter popups, no social proof widgets. The content quality is the
credibility signal. If it needs a "clap" button, the writing isn't good enough.
## Current Content Plan: Rage Series
Source: kenotron-ms/rage repo + ~/workspace/family/Work/Reference/BuildXL spec
| # | Title | Angle | Visuals Needed |
|---|-------|-------|----------------|
| 1 | Your Build Cache Is Lying to You | The silent stale cache problem. Make it concrete. | Flow: declared vs observed inputs. Before/after diagram of cache miss. |
| 2 | Two-Phase Fingerprinting: BuildXL's Deep Magic | WF→pathset→SF algorithm deep-dive. | Architecture: the two-phase lookup flow. Code walkthrough diagrams. |
| 3 | Hooking Syscalls Without a Kernel Driver | Three OS, three mechanisms. Most technically dense. | Side-by-side: macOS interpose / Linux eBPF / Windows Detours. Animated (Remotion): syscall interception flow. |
| 4 | TypeScript 7 Makes the Build Harness More Important | Counter-intuitive thesis. Widest reach. | Comparison: single-machine vs distributed. The parallelism table as a visual. |
| 5 | node_modules in a Content-Addressed Store | The unsexy problem that kills CI. | Flow: lockfile → CAS → hardlink restore. Before/after CI times. |
| 6 | What I Learned Maintaining Lage and Why I Rewrote It | Personal narrative, meta post. | Timeline: lage → BuildXL integration hack → rage. |
Each post stands alone but gains context from the series. The series landing page
shows progress (like makingsoftware.com's progress bar) and creates anticipation
for upcoming posts.