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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user