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
|
v
|
||||||
Commit + push
|
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