How the blog is organised, and how it should be

Proposal, 9 October 2026. Measured against the 1,906 items on disk at the time of counting, not against memory. The total moves while a run is writing, so the proportions are what matter here, not the last digit. Nothing here is implemented; the last section is the list of decisions that are yours.

What exists

Three levels are in use today. collection groups narrative arcs and exists only in _data/series.yml. series is the frontmatter field every post carries. group subdivides Under the Hood, the Exam Room’s cert tracks and Cooking’s recipe types.

Three places it strains

1. series means two different things. Forty of the sixty values are a narrative arc inside a collection (Drawing the Lines, The Merger, Killed on Schedule). The other twenty are top-level streams (Exam Room, Under the Hood, Cooking, Consulting and Craft). So the same field answers “which of the blog’s half-dozen things is this” and “which three-post arc of a fifteen-arc story is this”, and nothing in the data says which sense is meant. Every landing page works around it.

2. Under the Hood is two kinds of writing under one series name. The split is measurable and sharp: classify a group by how many of its titles begin How, What or Why, and the catalogue groups score 0 to 2 out of 22 to 30, while the topical groups score close to 100%.

508 against 268 is 65% of the series being a thing the series was not named for. The explainers grow by the dozen ideas on the shelf; the catalogues grow by 110 committed posts, 78 theory posts and 224 shelved ones. The name Under the Hood describes the 268 and always did.

3. The membership lists are hand-maintained in three places and have drifted again. CLAUDE.md names the narrative series and tells you to keep that list in step with NARR_COLLECTIONS and NARR_SERIES in scripts/reschedule.py, because when they last drifted apart 59 narrative posts were filed into the wrong publishing queue. The Floor, The Reproducible Result and The Standard of Proof are in _data/series.yml and in reschedule.py, and are absent from CLAUDE.md. 27 posts. The list drifted because it is a list, maintained by hand, in three files.

The proposal: two axes, both derived

Mode: how a reader should read it

Seven values. Every one of the 1,906 items classifies, with no residue once the three missing narrative series are added to the list.

Reader-facing labels, which are a separate question from the data values: The Exam Room, Stories, Under the Hood, Cooking, Reference, The Back Catalogue, In Practice. Four of those pages already exist. Reference is the one genuinely new top-level surface, and it is the one the next five years of writing fills.

Standing: fact or fiction

Orthogonal to mode, and the part that answers “factual, fiction, narrative or otherwise” directly.

• fact — 1,680 items. Every claim traces to a source. AWS figures come from AWS, as CLAUDE.md requires; Go figures come from code that was run; recipes come from cooking.
• fiction — 312 items. Invented companies, invented people, invented numbers, teaching a real technique. Greenbox’s subscriber curve, Tentpeg’s outage, the Casebook’s clients.

This is worth having as data rather than as a convention, for three reasons. A reader must never take AUD$340,000 of credited stock in a Greenbox post for a published figure, and one flag drives a standing line on every fiction post. check-currency.py already treats an invented figure differently from a real published price, and it currently infers that from context. And the narrative craft rules in NARRATIVE-CRAFT.md apply to exactly the fiction set and to nothing else, so the checks that enforce them get a precise domain instead of a list of collection names.

The -in-go tails are the fault this model nearly shipped. A tech implementation tail carries its narrative parent’s series, because that is how it is pegged to the parent and scheduled the day after it. Resolved by series alone it came out story and fiction, which is wrong twice: it is a Go walkthrough and its code is real. Eight posts. check-modes.py special-cases the -in-go suffix, and the lesson is that a resolution check catches an unresolved post and not a mis-resolved one, so the counts have to be read rather than trusted.

A third value, fiction-illustrating-fact, was considered and rejected: every fiction post on this blog teaches a real technique, so the value would be true of all 293 and carry no information.

Levels inside a mode do not change

mode  →  stream           →  group              →  post
exam     Exam Room           SAP-C03               one scenario
ref      Under the Hood      Data Structures       one structure
ref      The Workshop        (none)                one playbook
expl     Under the Hood      Trust                 one explainer
story    The Greenbox Story  Drawing the Lines     one chapter
pract    Consulting & Craft  Losing the Thread     one case post
kitchen  Cooking             Bread                 one recipe

Narrative’s collection becomes the stream and its arc becomes the group, which is what they always were. That resolves strain 1 without renaming a field in 1,906 files: series keeps holding the arc, and the stream is read from _data/series.yml, exactly as the collection pages already do.

Implementation: derive it, do not annotate it

No post frontmatter changes. No permalink changes. No redirects. Nothing re-dated. Mode and standing are a function of (series, group), so they belong in one data file:

# _data/modes.yml
streams:
  Exam Room:            { mode: exam,      standing: fact }
  The Workshop:         { mode: reference,  standing: fact }
  Cooking:              { mode: kitchen,    standing: fact }
  Consulting and Craft: { mode: practice,   standing: fact }
  High Performance Teams: { mode: practice, standing: fact }
  Under the Hood:       { mode: explainer,  standing: fact }   # default
collections:            # every narrative collection and standalone series
  The Greenbox Story:   { mode: story,      standing: fiction }
  ...
groups:                 # overrides, where a group's mode differs from its stream's
  Data Structures:      { mode: reference }
  Patterns:             { mode: reference }
  Integration:          { mode: reference }
  Applied Patterns:     { mode: reference }
  Algorithms:           { mode: reference }

Properties worth having: a new run adds one line; the file is the single source for CLAUDE.md, reschedule.py and the landing pages, so strain 3 cannot recur; and a check can fail when a post’s (series, group) resolves to nothing, which is how the three missing narrative series would have been caught the day they were added.

The one real migration is reschedule.py and CLAUDE.md reading the file instead of carrying their own lists, and check-narrative-mode.py (new) failing on an unclassified post.

What changes that a reader sees

1. A Reference landing page, listing the catalogues as catalogues. It is the surface the next five years of writing goes to, and today those 97 posts are findable only through a series page named for the other 256.
2. The group banner names the catalogue, not the series. “Part 7 of the Data Structures catalogue” rather than “Part 7 of the Data Structures series · Under the Hood”, which currently makes a reference post look like an instalment of an explainer series.
3. A standing line on fiction. One sentence, on all 293, saying the company and its numbers are invented and the technique is not.
4. Nothing else moves. Every existing URL keeps working, because none of this touches a permalink.

Decisions that are yours

1. Does Reference get its own top-level surface, or stay inside Under the Hood? The 65% number says split. The counter-argument is that Under the Hood is the brand and a reader does not care about the taxonomy.
2. Reader-facing label for reference. Reference is honest and dull. The Shelf fits the house register. The Library collides with the information-science language now going into The Archive.
3. Is archive its own mode or just old explainers? The 108 posts from 2008 to 2014 carry legacy markup that CI deliberately skips. Calling them a mode is honest; folding them into explainer would pull them into checks they were exempted from.
4. Does practice stay two streams or become one? Consulting and Craft is 65 posts and High Performance Teams is 15, and they answer the same reader question.
5. Week Notes is one item in kitchen. It drives cooking.ics and is arguably its own thing.

One thing to fix while it is cheap

A narrative series is titled The Numbers Were Wearing Makeup. That is the “wearing” construction CLAUDE.md bans by name, in a series title, and the rule exists because the tic mutates and a grep for a fixed list misses it. All three of its posts are unpublished (2029-05-08 to 2029-05-22), so the title, the series.yml entry, the landing page and the three permalinks can all change at no cost. After publication none of that is true.

Decisions, 9 October 2026

Taken, not proposed. Cooking being separate from the user-facing blog is yours; the rest follow from it and from the arithmetic in the schedule section.

There are three front doors, not one

This is the decision Cooking forces, and it is the one everything else hangs off. Cooking is not a section of the blog, so it is not a mode inside the blog’s navigation: it is a separate surface with its own landing page and its own feed, which it already has. Once that is true for Cooking, the same test applies to the Exam Room, and the Exam Room passes it harder: 841 posts, a distinct audience sitting a certification, its own cert pages and checklists, and a shelf life set by AWS retiring exams rather than by anything editorial.

Today the main feed carries all three, so a reader following the blog sees ten posts a week of which eight are AWS scenarios. That is the overwhelm and the boredom in one: too much, and too much of it the same.

1. Reference gets its own surface. Yes

549 reference posts are queued or planned against 230 explainers. A surface named for the smaller half is the wrong name on the door, and the 65% figure is only the start of it.

The clinching argument is not the count, it is that the two are read differently. An explainer is read once, so it wants a next-post link and a reading order. A reference post is returned to, so it wants its catalogue’s whole index visible and no notion of “next”. Those are different pages, and one series cannot be both.

2. Its label is The Catalogues

The register is places and activities: Under the Hood, The Exam Room, The Workshop, In Practice, Cooking. Reference is a category rather than a place and reads as a filing cabinet.

The Shelf fits the register and was the first choice, then failed on a collision: “shelf” already means the idea shelf throughout BACKLOG.md, CLAUDE.md and the three NEXT-*-IDEAS.md files, and reusing it for the published surface would make every existing note ambiguous.

The Catalogues is accurate rather than clever. These genuinely are catalogues, and named ones: Gamma’s patterns, Hohpe and Woolf’s, Fowler’s refactorings, Nygard’s stability patterns, Joshi’s distributed systems, Russell and Norvig. The plural says there are many, which is the thing a reader needs to know on arrival. /writing/the-catalogues/.

3. archive stays its own mode

CI deliberately excludes /u/ and the date-based /YYYY/ paths from link checking, because the 2008 to 2014 posts carry legacy markup, http links and <a name> anchors that are not being edited. Folding those 108 posts into explainer pulls them into checks they were exempted from on purpose, and the next person to see a red build would “fix” eighteen-year-old posts.

Label The Back Catalogue. It needs no publishing slot, because all 108 are already out.

4. practice becomes one stream, In Practice

Consulting and Craft is 65 posts and High Performance Teams is 15, and they answer the same reader question. Fifteen posts, thirteen of them unpublished, cannot carry a front door of their own.

High Performance Teams survives as a group inside In Practice, which costs nothing, keeps the arcs intact, and leaves every permalink alone. The /writing/in-practice/ page already exists.

5. Week Notes go with Cooking

They are meal plans that drive cooking.ics, which makes them the most personal thing on the site and the furthest from the blog’s public face. They stay in kitchen as a group, on the Cooking surface, and take no main-feed slot.

The schedule

Three surfaces, three rates, and each rate set by a different constraint. That is the whole design, and the reason the current single cadence cannot work: one queue is being asked to serve a reader’s attention span, AWS’s exam release cycle, and how often somebody cooks something worth writing down.

What the rate is set by

The blog: four posts a week. Set by a reader’s attention. Four is enough to be worth following and few enough to read all of. It gives a clean three-day gap across the weekend, which is where “not overwhelming” actually comes from: a feed with a rhythm, not a drip.

The Exam Room: eight a week. Set by AWS, not by taste. A track has to land inside a quarter, because exam versions move and a track published over a year is obsolete before it finishes. SAP-C02 became SAP-C03 across 97 posts; two more bumps are in flight. At eight a week the remaining 771 posts clear by August 2028. At four a week they finish mid-2030, which is past two more version bumps, so half the track would be retagged before it published. Eight is not a firehose here, it is the minimum that works, and it is survivable precisely because this is its own feed and nobody reads it unless they are sitting the exam.

Cooking: one a week, Sunday. Set by cooking. Written as cooked, as now.

The week

Tuesday stays narrative, which it already is and which readers already know. Thursday stays the mixed slot it already is, minus the catalogues that were crowding it out. The two catalogue slots sit on Wednesday and Friday rather than back to back, so no two consecutive days in the blog’s feed carry the same mode.

Why this allocation and not another

The allocation is not a preference, it is what makes the queues finish together. Give each mode its share and they land within six months:

What today’s allocation does instead: reference finishes in 2043. One Thursday slot shared between the catalogues, the explainers, In Practice and The Workshop gives reference 0.63 posts a week against 549 queued, which is seventeen years. That is the actual problem, and no amount of reordering fixes it, because it is a division.

The Thursday slot alternates explainer and In Practice while In Practice has stock, which is about two and a half years at that rate, then explainers take the whole slot. Nothing runs dry while something else backs up.

Three rules that keep it from being boring

1. No two consecutive blog posts from the same group. Wednesday and Friday come from different catalogues, so two runs publish in parallel on alternating slots rather than one run publishing out solidly for fourteen weeks. Each run keeps its internal order, which matters where a run’s first post sets up vocabulary the rest uses; the reader just gets it every other week alongside something else. This is a change to how relay-exam-queue.py and reschedule.py lay a run, and it is worth scripting as a check: a run laid into consecutive slots of the same group is the monotony failure, and it is detectable.

2. Narrative keeps its blocks and its blank Tuesdays. One arc, then a blank week, then an arc from a different collection. That device already exists and is already why story’s 273 posts reach mid-2032 rather than January. Do not let reschedule.py --apply flatten it, as CLAUDE.md already warns.

3. A catalogue run is at most about thirty posts. At two slots a week that is fifteen weeks, which is a season. The 224-post wider shelf is sixteen catalogues, not one, and should stay that way; a sixty-post run would occupy one of the two slots for seven months.

What has to be built

In order, and none of it touches a permalink:

1. _data/modes.yml — mode and standing per stream, collection and group. Written in this commit. Zero post edits.
2. scripts/check-modes.py --strict — fails when a post’s (series, group) resolves to no mode. This is what would have caught The Floor, The Reproducible Result and The Standard of Proof the day they were added.
3. CLAUDE.md and scripts/reschedule.py read _data/modes.yml instead of carrying their own lists. Strain 3 cannot recur after this.
4. /writing/the-catalogues/ landing page, and the group banner naming the catalogue rather than the series.
5. A separate Exam Room feed, and the main feed filtered to the blog’s four publishing modes. — /writing/exam-room/atom.xml written, and the main feed now excludes Exam Room and Flash Cards. Also added feed discovery for all three front doors, which did not exist at all: no rel="alternate" anywhere in the layouts, so a reader had to know a feed’s URL.
6. The standing line on all 293 fiction posts. — written, on story-banner.html and collection-banner.html, which between them cover every narrative post. The count is 312, not 293: the first measurement left out The Floor, The Reproducible Result and The Standard of Proof, which is the same drift this architecture exists to stop, and it caught me too.
7. Re-lay the three queues onto the new week. This moves unpublished dates only; scripts/check-published.py is the guard, and nothing already out may move.