The first example carries too much weight

The first runnable example teaches more than the paragraph around it.

Readers copy its naming, infer its boundaries, and decide what kind of system they are seeing. That example needs to be honest about the subject.

A simple call:

const result = await run(input)

implies a stateless, broadly safe operation. If the real boundary includes cancellation and a timeout, show some of it:

const result = await client.run({
  input,
  timeoutMs: 10_000,
  signal: abortController.signal,
})

Names teach too. A variable called “value” hides whether it is raw, parsed, trusted, or cached. Distinguishing raw response from parsed profile shows the boundary.

Include the error path that defines the topic. A tool example may need schema validation. A file example may need workspace scope. A form example may need the failure state.

Keep the unit small enough to teach one idea, but real enough not to teach the wrong rule. An eval case, one embedding query, one cache key, or one sync conflict can carry the subject without introducing an imaginary architecture.

Before publishing, ask:

• what assumption will readers copy?
• which line will they paste?
• what important boundary is invisible?
• does a later section contradict this shape?

The first example is a promise about what the article values. Write it as if it will become somebody’s starting point.