Engagement patterns for article series

How the series articles are structured to serve every experience level at once, and to push a passive read toward active practice. Worked out on the Borrow Checker post 1; meant to be reused verbatim on every series after it. The value of writing it down is that the convention is the product — by post 3 a reader knows what a grey "New to…" box means and whether to open it.

The core move: one spine, typed dropdowns

Targeting "all audiences" fails if the main text tries to serve everyone — the beginner drowns, the expert skims. So:

Pick one baseline level for the spine. The article must read top-to-bottom, complete and correct, with every dropdown closed. Dropdowns are detours, never load-bearing. If a reader has to open one to follow the argument, the leveling is broken and the content belongs in the spine.

Baseline chosen for the Borrow Checker series: a working programmer who may not know any Rust. Higher (assume fluent Rust) tightens the spine but narrows the top of the funnel; lower (assume little programming) widens it but bores the likeliest reader. Middle is the default unless a series has a reason to move it.

The dropdown vocabulary — three types, fixed

A small, consistent set. Label by who it's for, not what's in it — the label is a routing decision the reader makes in half a second.

• Floor — "New to X?" Pulls a struggling reader up to the spine. Prereqs, defined terms, "what even is &s[0]." This doubles as the readiness check (see below).
• Deep — "Already comfortable? The precise version." Lets an expert drop down into the formal detail without cluttering the spine. The RFC, the edge case, the forward-reference to a later post.
• Cross — "Coming from Go / C / Python?" Lateral. Especially load-bearing for language/systems topics, where most confusion is "but in language X this was fine." The post-1 Go bug is this move formalized into a slot.

Implement with native <details><summary> today — it renders in Docusaurus MDX with zero components. If the pattern proves out, then extract <Floor>, <Deep>, <Cross lang="go"> components so labels and styling are consistent and you're not hand-rolling <details> forty times. Prove on one, then componentize — same order as everything else.

Readiness is an invitation, not a gate

A "how ready are you?" gate at the top adds friction and bounces the exact beginner you want to keep. Don't build a separate thing: the Floor dropdowns already are the readiness check, presented as a welcome instead of a test. A reader who opens two of them and feels fine is ready; one who opens them and is still lost has learned that cheaply, at the top, without being told "you failed the quiz."

Predict-before-reveal — a quiz with no infrastructure

The strongest engagement mechanic in post 1 costs nothing: a <details> that asks the reader to commit to a guess before scrolling. "Which line does the compiler reject — the pointer take, the push, or the write? [Reveal]." The act of predicting is what creates retention; being right or wrong is secondary. Use it at every point where the reader can plausibly guess the outcome.

Learning by doing — convert the mobile read into laptop practice

The honest problem: most reads are passive, on mobile, and end there. Levers that work today with existing infrastructure:

• A concrete "Try it" block with a copy-paste clone command and three specific things to do — not "explore the repo," but "run this, then break it this exact way, then watch it disappear." Specific dares beat open invitations.
• Comment prompts that ask for output. "Post your exact error — I read them." Sign-in + comments already exist. This is also a return-hook: a reader who comments has a reason to come back (replies, reactions).
• The contrast dare. "Run it with spare capacity and watch the bug vanish." Doing the same thing twice with one variable changed is how the LINQ-on-a-CSV kind of learning actually happens — try, observe, try again.

The one component worth building: the decision quiz

Not trivia — a decision quiz. "Given these choices, how would you implement this?" It matters because it is the Borrow Checker series' spine made interactive: the whole arc is four answers to one question (how do you represent the links — Box, Rc<RefCell>, arena indices, unsafe?). A component where the reader picks an approach and each choice reveals its tradeoff and links to the post that walks it turns the series structure into something playable. Build this one; skip generic trivia.

Animation — the decided approach

"Visual, watch-what-happens" animations are their own class of engagement (the data-structure diagram that moves). The approach, settled by testing it on the LRU cache visualization:

Code, not GIF. CSS transitions/keyframes first; a library only if code can't do it. Reasons: a GIF can't be edited, re-themed, or made interactive, and it's a binary blob in the repo — the one committed .gif on the site (static/img/old-portfolio.gif) is exactly that problem. The site already has no animation dependencies and its existing motion (e.g. ExplorerNudge.module.css) is hand-rolled keyframes, so this stays on the house pattern rather than adding a build dependency.

The mechanism that generalizes: absolutely-position the moving pieces and let transition: transform do the work — set each element's target position/opacity in ~40 lines of JS and CSS animates between states. It's version-controllable, theme-aware (CSS vars), scales on mobile (no fixed raster), and — the real payoff — the same component turns interactive by swapping the timed script for click or drag handlers. So the "watch it" animation and the "drag the thing" quiz are one component at two settings, which is why this beats both GIF and a heavier runtime.

Reserve a designed-animation runtime (Rive, Lottie) for things that are genuinely illustration rather than data — e.g. the crustacean mascot growing / getting netted, which is character animation, not a data structure in motion.

Parked idea: a meta-article on how to make these — the GIF-vs-code-vs-library tradeoff, the position-and-transition trick — is worth writing once a few of these exist and the pattern is proven. It's the kind of thing that's scarce and gets read.

Animation design rules (growing list)

Learned by making them; add to this as more get built. These are about comprehension, which is the actual job — a technically slick animation you have to watch fifteen times has failed.

• Start from the empty state. Don't open mid-scene with the structure already populated. Initialize nothing, then build up one element at a time — the construction is the explanation. (An LRU animation that starts full looks like a finished diagram; one that starts empty and fills A, B, C, D teaches you what the slots mean before anything moves.)
• One idea per beat, and pace for a single watch. If the viewer has to loop it to follow, it's too fast or too dense. Slow the default, and put an explicit caption on every beat.
• Give control, don't dictate speed. Play/pause plus step-forward/back solves pacing better than any fixed duration — different viewers need different speeds, and stepping lets someone sit on the one beat that confused them. This is the reusable harness; build it once.
• Show the distinguishing case, not just the happy path. The LRU animation has to include a get that promotes an item, or it's indistinguishable from a FIFO queue — the access-order eviction is the whole point.

Bespoke by default. Expect each animation's choreography to be a one-off; what generalizes is the harness (empty-start convention, playback controls, the position-and-transition mechanism), not the specific motion. Build the harness to reuse; write the choreography fresh each time.

Future direction: a synchronized code + animation view — the code beside the visual, highlighting the current line as the animation advances that step, so the reader sees which line caused which change. A second, richer mode of the same harness.

Series-specific skin: crustacean leveling (Rust)

A gamified progression that makes skill level visible and playful. Specific to the Rust series, but a reusable idea — each series can have its own mascot arc.

It works because it's grounded in real Rust culture, not invented. The community already calls itself Rustaceans, and Rust's unofficial mascot is Ferris, a crab — a crustacean. The twist is to make the size of the crustacean the skill level. Everyone starts as krill — tiny, soft, just-hatched — no matter how much C++ or Rust they can read, because the series' whole thesis is that reading isn't doing. You level up by running the exercises: krill → shrimp → crab (Ferris) → lobster.

There's room to take the taxonomy as far as it's funny. The tiers can be actual scientific names, differentiating species of crab and lobster as the levels climb (a fiddler crab is not a coconut crab), which rewards the reader who notices and costs nothing for the one who doesn't. And the arc has a natural endgame past "expert": you don't stop at the biggest lobster — you get plated and smothered in butter. Mastery as the pot. It's a joke that lands harder the more the reader has invested, which is exactly who it's for.

The playful layer: small animations tied to the predict-before-reveal and quiz moments. Answer correctly and your crustacean grows a size (or advances a species); miss it and it gets scooped by a fishing net, then pops back — no real penalty, the point is delight, not punishment. Deliberately stupid, deliberately mobile-friendly. Engagement over dignity.

Status: idea. The metaphor and copy can start appearing in the Rust articles' prose now (framing the reader as a krill leveling up); the animation is a component build under the site-wide Interactivity initiative (internal/major-todos-technical.md).

---

Parked — return & retention infrastructure (not built, not scheduled)

Recorded so it isn't re-derived from scratch. This is genuinely separate work from the article structure above, and bigger.

The gap: the site can be visited (OAuth, comments, reactions all live), but there's no built-in reason to come back. For code learning specifically, a single read rarely lands — spaced repetition and nudges are what convert interest into a skill. Half-formed directions, in rough order of effort:

• Progress a reader can see. "You've read 3 of 9 in this series" / a checkable "I ran the exercise" marker per post. Ties to the series field and the per-user data the backend already stores.
• Opt-in nudges. "Want a reminder to actually try this?" → an email a few days out. Low-tech, high-signal, and honest about the mobile-read problem ("you said you'd run this — here's the clone command again").
• Send-to-self. A one-tap "email me this repo + commands" for the mobile reader who can't run code where they're standing.
• The game idea (already sketched elsewhere, long parked) is a heavier version of the same instinct and stays out of scope here.

None of this blocks writing the articles. Flagged because "engagement → retention" is the real lever, and the article-side patterns above are the part that's achievable now.