TUTORIAL OR REFERENCE, NEVER BOTH
One subject.
Two doors.
The explanation lives on one page and the clause that governs it on another, and every reader has to guess which half holds the answer they came for.
Should documentation explain or specify?
Both, at one address. Splitting a subject into a tutorial and a reference asks the reader to guess which half holds their answer, and guarantees the two will drift apart. HAUSE's Lens keeps them as depths of one thing — the explanation, the object itself, and the normative clause — on a single URL, with the chosen depth remembered across pages and written into the fragment. A reader who thinks in clauses stays in clauses.
01 / HOW YOU MEET IT
Depth is a design problem, not a navigation problem.
The introduction is charming and imprecise. The reference is precise and unreadable. They disagree in one detail, and the reader who noticed is the one who needed that detail most — so they open both in adjacent tabs and reconcile the documentation by hand, which is the job the documentation was for.
02 / THE RESPONSE, IN YOUR HANDS
Change the depth. Keep the address.
Explore the forms below. This is the response implemented in HAUSE.
THIS PROBLEM — AT THREE DEPTHS
THE COST OF THE SPLIT
Two pages about one subject are two things to keep true. The reader pays first — guessing which half holds their answer — and the writer pays afterwards, because the half with the traffic and the half with the precision are rarely the same half, and neither review cycle catches the disagreement between them.
YOU ARE OPERATING IT
This is a Lens: the control above, three panels beneath, every panel in the DOM whether or not you clicked it. Your choice is remembered in localStorage and written into the URL fragment, so this page can be sent to someone at the depth you were reading — and the next chapter opens where you left off rather than back at the introduction.
THE CONTRACT — components/forms/Lens.tsx
export type LensDepth = {
/** Short, stable, and used as the URL fragment — "learn", "inspect", "spec". */
id: string;
label: string;
/** What this depth gives, in a few words. */
hint: string;
content: React.ReactNode;
};
export type LensProps = {
kicker: string;
/** The concept being looked at, for the accessible name. */
concept: string;
depths: LensDepth[];
/** Persist the reader's chosen depth across pages. Default true. */
remember?: boolean;
caption?: string;
};
export function Lens({ kicker, concept, depths, remember = true, caption }: LensProps)Read out of the library at build time, like every other contract on this site.
The demonstration is the argument: one subject, one URL, three depths — and the depth you pick here is the depth the rest of the site will greet you with.
Depth — learn: what the split costs · inspect: the instrument, running · spec: the props, verbatim. One concept, one URL, the depth of your choosing.
03 / BENEATH THE SURFACE
Why the failure keeps returning.
The two audiences are real, so splitting them feels obvious — and it is a split of pages where the actual difference is depth. Once they are two pages they have two authors, two review cycles and two rates of decay, and the precise one wins the arguments while the readable one gets the traffic.
TAKE THE RESPONSE WITH YOU
Give it a form.
Lens
One concept at several depths — the explanation, the object, the clause — on one URL, with the reader's depth remembered.
Excerpt
Someone else's words, typeset — verbatim source material with its markdown rendered and its trims marked.
Snippet
A labeled block of code or terminal output, verbatim on the ink — the on-ramp form, promoted when two sites needed the same shape.
Anatomy
An annotated cutaway — one artifact drawn as its layers, fully disclosed.
PUBLISHED 31 AUG 2026 · VERSION 1.0
CITEsite build 3ee5339 · built 2026-09-09
CITE THIS
Article · 1.0
Hay, C. (2026). Tutorial or reference, never both. In HAUSE — the problems (Version 1.0). hause.design. https://hause.design/problems/tutorial-or-reference-never-both
An argument is a published object: dated, versioned, and referenceable — which is the subject of one of these pages and the practice of all of them.