The voice and structure for nodes on wanderland.dev. Empirical — captures patterns observable across the existing corpus. Revised as the corpus grows.
Documentation is a present-tense factual account. The reader opens the page cold; the text describes the system as it stands.
It's also a conversation with a specific person. The reader is working through the material with us — they'll install, configure, name, decide. When the reader has agency over what's being described, write to them as "you." When we're walking through a step together (running a command, generating a cassette), "we." Third person ("the framework," "the runtime," "the boundary") is for what the system does mechanically, where no reader decision is involved.
The pitfall is to fall back on abstract-institutional subjects — "the site," "the developer," "a team," "the user" — when "you" is what we mean. That reads as broadcasting at an audience instead of working with a person. The relationship between writer and reader is what makes a tutorial land; abstract subjects break it.
The Changelog section is the one place narrative-of-change belongs. Body text describes the present.
The empirical pitfalls. These are the shapes most often caught in revision — they look tight on the page but fight the reader. Each entry names the pattern, says why it's worth avoiding, and shows a real before/after pair.
"The site decides," "the developer chooses," "the operator names," "the team picks" — these put a third-person frame around something the reader is actually doing. When agency or decision is in play, the subject is "you." Generic abstract subjects work for describing a type of system ("a site that uses both regions..."), but break the moment a choice is being made. Watch every sentence where the reader is the actual decider — if it doesn't say "you," it's probably hiding the reader behind a fake subject.
Before:
The naming is up to the site — the registry doesn't enforce a convention.
After:
The naming strategy is up to you when you're developing your site/tool, the registry doesn't enforce a convention.
Before:
The site declares the per-service SDK gem in the
Gemfileand then mounts an adapter for it.
After:
We declare the per-service SDK gem in the
Gemfileand then mount an adapter for it.
Imperatives and bare predicates ("Generate them by...", "Replay needs cassettes.") read as a manual. Use a person — first-person plural ("we") or second-person ("you") — to walk the reader through. Reserve bare imperatives for actual numbered steps, where the imperative is the instruction.
Before:
Replay needs cassettes. Generate them by running a live request with
--wanderland-record-to.
After:
To use replay mode, we need cassettes. We generate them by running a live request with
--wanderland-record-to.
Stacking "same X, same Y, same Z" with em-dashes reads as rhetoric. Same content as a couple of plain sentences reads as explanation.
Before:
A boundary that calls
cfn.describe_stacksreads the same way as a boundary that callshttp.get— same contract, same mode discipline, same cassette story; the substrate underneath is what changes.
After:
A boundary that calls
cfn.describe_stackswill act the same way as a boundary that callshttp.get. Both use the same contract, the samelive|mock|replaymode selections and both use the same YAML based cassettes. The only difference is the IO with the external system.
Using a quoted phrase as a noun ("the X case") is verbal compression that makes the reader unpack the quote back into the idea. Just write the idea.
Before:
Replay covers the "what does this boundary do against the real upstream" case. Mock covers the "what does this boundary do when the upstream returns a shape we can't reliably get on demand" case.
After:
Replay covers the case where we want to test the boundary against the actual upstream's response. Mock covers the case where we need to test against a response shape the upstream won't reliably produce on demand.
"Reads as", "doubles as", "lands as", "comes off as", "sits with" — these reach for register the prose doesn't need. Plain verbs ("act", "do", "use", "make", "show", "is") match the technical content better. Save the literary ones for places where they're more accurate, not more impressive.
Before:
A boundary that calls
cfn.describe_stacksreads the same way as a boundary that callshttp.get.
After:
A boundary that calls
cfn.describe_stackswill act the same way as a boundary that callshttp.get.
When a thought has two parts, two periods are clearer than one comma followed by a "with X" or "since Y" clause hanging off the main statement.
Before:
It's the cheapest option, with no upstream drift since it's the bytes you saw.
After:
It's the cheapest option. There's no upstream drift because the response is exactly what was recorded.
The "the X is what changes / what does Y / what makes Z" shape sounds weighty but buries the verb. Direct subject-verb is clearer.
Before:
The substrate underneath is what changes.
After:
The only difference is the IO with the external system.
Phrases like "the bytes you saw" or "the moment it lands" are punchy in isolation but ask the reader to reconstruct the antecedent. Plain restating beats compression.
Before:
...no upstream drift since it's the bytes you saw.
After:
...no upstream drift because the response is exactly what was recorded.
Arrows (→) work in tables and code blocks; in prose they're a typographic shortcut for what should be a sentence with a subject and verb.
Before:
The runtime checks at first call that an adapter named
:ec2is mounted; missing →Wanderland::Adapters::UnknownAdapterError.
After:
The runtime checks at first call that an adapter named
:ec2is mounted. If it's missing, the boundary raisesWanderland::Adapters::UnknownAdapterError.
A single fragment can be punctuation ("Three modes:"). Several in a row reads as slide-deck rhythm. If a paragraph is mostly fragments, expand the rhythmic ones into full sentences.
Common offenders: "Production." "Calls delegate." "Three modes." Fine individually as section openers or list lead-ins; performative when stacked back-to-back-to-back through a paragraph.
Each node fits one of four shapes. The shape determines opener, structure, and tone.
Second-person, learning-by-doing. Opens by orienting the reader: where they are in a series, what today's session produces, what they'll be able to do at the end.
A diff between the smolchalk tutorial style and the vivarta-jenkins-on-k8s tutorial style. Both share the project voice; pacing shifts with stakes.
What's the same. Inclusive "we" with intent — "Today we're going to put Jenkins…", "we'll meet", "we'll see". Outcomes named upfront as concrete capabilities ("When you're done you'll be able to:"). Time budget — "about two hours the first time, less than ten minutes a second time." Plain language. No marketing voice. No emoji. Calm "what you have now" close. Opinions stated as opinions — "We treat ECS-on-Fargate as the contingency for the Jenkins controller if the K8s path runs into a wall…"
What's different. Vivarta tutorials lean much harder into concept-before-mechanic. There are seven explainer sections before Step 0 starts: "Where we're going to run this", "A map of the moving parts", "Glossary up front", "What OrbStack gives us", "The Kubernetes vocabulary we'll use", "How Jenkins separates the controller from the agents", "Why we configure Jenkins from a file (JCasC)", "Why we build images with BuildKit, not Docker-in-Docker". Each is a few paragraphs of prose, not a bulleted list. Only then does the first command run.
That pre-step block does specific work: surveys the alternatives. "We have four candidate places to run real workloads, and it's worth naming each one before we pick." — Compose, k8s-local, k8s-CoreWeave, ECS-Fargate each get a paragraph naming what they're for and why they aren't this. The reader leaves understanding not just what we picked but the shape of the space we picked from.
Other patterns to copy.
Anatomy: paragraph that walks the chosen flags/values, line by line. Reader knows what each knob is doing without reading docs.The split that makes this work. Smolchalk is for parents and educators (low technical floor, fast reward) — so it leans on do-and-see. Vivarta-on-k8s is for engineers wiring production infra (high complexity, irreversible mistakes possible) — so it leans on understand-then-do. Both share the same voice; the pacing of explanation is what shifts.
This is the first walkthrough in the Engine tutorial series. Today
we're going to scaffold a brand-new wanderland-core application
called `wanderland-engine`, get it answering on port 9295 locally,
then package the same code as a Docker image so `docker compose up`
brings it up the same way every time.
When you're done you'll be able to:
- spawn the engine in a container and hit it from your host
- ping the liveness triptych — /health, /status, /healthcheck — for
service answers in increasing depth
- ...
You won't write a single custom boundary today — that lands in
tutorial 2.
Structure:
## What X is section before any code. Define the concept, name its parts, contrast it with what the reader already knows. Run-on prose is fine; the reader should leave the section with a working mental model before the first command.What to introduce vs assume is governed by the Tutorial Storyboard — the curriculum map that catalogs every post's introduces and assumes lists. Read the storyboard before drafting; update it when the post settles. Style guide names voice and shape; storyboard names concept order — both apply.
Examples that hit this depth: Hello World, Writing Boundaries, Adapter Modes, Walking the Grid.
Factual catalogue of an API surface. Dry, terse, present-tense.
The framework's reflective surface: runtime endpoints that report
what's registered, what's configured, and what each request actually
walked through. Everything the engine knows about its own structure
is exposed as HTTP routes, reachable with nothing but `curl`.
Structure: concept sections with response shapes (code fence) and field bullet lists. Source file pointer near the end.
Examples: Introspection, Config, Envelope Schema.
When the node catalogues a set of similar things — registered resolvers, overlay operators, fence types, adapter modes — lead with a per-entry reference guide and follow with a development-oriented spec.
The reference guide is one ### !Name (or ### name) per entry. Each entry carries:
The spec sits below the reference guide and covers architecture, the resolver/operator interface, error model, and a numbered "Adding a new
The pattern fits when the catalogue size is bounded — single digits to small dozens — and entries share a uniform shape. For very large catalogues, the spec section compresses to a pointer at the architecture node.
Catalogue only what's wired up in the code. Entries that exist in older drafts but aren't registered move to the changelog as a removal note rather than carrying speculative API forward.
Canonical example: Template Engine.
Task-oriented. Walks the path that solves a class of problem.
The request lifecycle. How a YAML config becomes a listening service,
how a request arrives, routes to a boundary chain, walks the chain,
and returns a response — with a signed, hash-linked record of
everything that happened.
Structure: lifecycle diagram (ASCII), shape-of-X sections, best-practices subsection where applicable, "Contents" listing of leaf nodes when the node is a category index.
Examples: Engine Guide, Scenarios How-To.
Discusses how something composes or why a pattern exists. Reserve for architectural pieces.
Examples: Boundary Chains, Web Components.
Every node carries:
# H1 title at the top.<oculus-node> cross-ref to a parent or related guide section, immediately under the H1.## H2 sections (and ### H3 sub-sections where the section has internal structure).## Source (reference docs) — file pointer(s) under lib/.## Site Audit — the `
## Maintenance
Empirical. New conventions land here as they appear in the corpus. Keep entries short; cross-link to canonical examples rather than enumerating every variation.
## Site Audit
*wanderland.dev*
<!--wld-shield-2-->