Documentation

Cross-reference the surface with {@link}

src

When a doc comment names a related symbol — the layer that provides it, the helper that folds it, the error it throws — wrap it in {@link name} so a reader can navigate the surface instead of grepping for it. A doc comment is a node in a graph, not an island.

/** The resource's peer clients, for its own cross-node logic. Requires {@link peersLayer}; fold them
 *  with {@link combineQuery} / {@link combineStream}. */

Comment what a junior dev couldnt infer

srcexamples

An inline comment carries what the code cant show a competent-but-junior reader: why this line, not what it does. A type-level trick, an Effect layer-ordering constraint, runtime ownership, a timing subtlety, a non-obvious workaround. If a reader who knows the language would ask wait, why?, answer it. If they wouldnt, stay silent — never narrate what the code already says.

// ✅ good — answers the "why?" a junior would have
// provideMerge, not provide: a bare provide prunes the serve layers off httpServer
const node = Node.httpServer([Counter.serve]).pipe(Layer.provideMerge(deps))

// ❌ bad — restates the obvious
const total = a + b // add a and b

Make the Invisible Visible

docs

Composition shown beats composition described. Find the dynamic the static medium hides — type evolution under combinators, a Handle that stays the same while the Layer changes, work moving through a queue — invent one consistent device to render it, and use that device everywhere the dynamic appears. Readers learn the device once; then it compounds across pages. Prefer three short frames (or three annotated fences) over a paragraph that narrates motion.

In this book the default device is the Twoslash fence with a ---cut--- preamble and inline type comments on the Handle. Stay with that device unless a page has a stronger domain-specific one, and then use that one consistently on that subject.

Earn the Abstraction

docs

Lead with the wall the reader will hit — the try/catch, the hand-rolled client, the untyped Promise — then present the abstraction as the release of pressure they already feel. An unmotivated abstraction reads as ceremony; a motivated one reads as inevitable. This matters most for the best features, where the temptation to open with the fireworks is strongest.

Minimal Deltas

docs

Each example isolates exactly the one concept the page is teaching, presented as the smallest change from the prior fence — not a fresh full program the reader must diff mentally. A sequence of small deltas teaches the axis of variation; three complete dumps teach less. Prefer ---cut--- / repeated preambles over restarting from imports every time. Deltas over dumps.

Present-Tense, Imperative, Affirmative

docs

Describe behavior in present tense — the app opens, not will open — so the system reads as a stable set of facts. Address the reader directly and tell them to act: Tap Settings, not the user should navigate to. Prefer the affirmative: enter eight or more characters beats dont use fewer than eight. Active voice throughout, with the actor named.

One Door for Tasks, a Staircase to the Machinery

docs

Tutorials and how-tos stay clean of internals — the reader accomplishes the task without learning the mechanism. Explanation and architecture pages carry the mechanism, clearly labeled, because for hard features how does this even work is load-bearing for trust. One front door for tasks; a well-marked staircase downstairs. Do not force the task-doer downstairs, and do not leave the curious reader without a staircase. Link the staircase; do not dump it in the hallway.

No AI Fingerprints

docs

Cut patterns that read as machine-smoothed copy rather than a person making choices:

• Bold-prefix bullets (**Feature:** description)

• Corrective antithesis (Not X. But Y.)

• Dramatic pivots (Heres the catch, But heres the thing)

• Throat-clearing (Lets dive in, In this guide well)

• Gift-wrapped endings and mid-page scaffolds (In summary, Putting it together)

• Soft hedges and enthusiasm padding (worth noting, really shines, ensures)

• Stacks of same-length punch sentences with no rhythm variation

State the point. Vary sentence length. Name concrete actors and verbs. Complements No Simply and Show, dont tell.

Show, dont tell

docs

A guide earns trust with real, working code a reader can run — not adjectives about how clean or powerful the thing is. Lead with the code doing the job and let it carry the claim; cut effortless, elegant, simply. If a sentence would survive being replaced by a code block, replace it.

// ✅ good — the feature, shown
const worker = QueueHyperlink.serve(Emails, { effect: sendEmail }).pipe(nodeServer(3001))

// ❌ bad — telling, not showing
// "hyperlink-ts makes serving a queue across runtimes effortless and elegant."

The glossary defines what the API docs cant

docs

The API reference documents symbols — every exported function and type. The glossary documents concepts: Tag, Service, Contract, cross-runtime service — the vocabulary a reader needs that no single export names. Define each such term once, in the glossary, and link to it (/docs/glossary#term) the first time it matters on a page. A term a doc comment already defines belongs in the API docs, not here.

Capitalize the domain terms

docs

The toolkits concepts are proper terms — Tag, Service, Contract, Hyperlink, Layer, Handle, Node, Implementation — and read as such: capitalized, so a Tag (the concept) is distinct from the ordinary word. The glossary is the list of what counts; a lowercase tag in prose reads as a mistake. Where a word is genuinely generic — reach it through an HTTP client — leave it be; capitalize the term when it names the concept, not every time the letters appear.