Guidance placed at the point of use is more likely to be read than a docs site

What it is

In-context usage guidance sits next to the call site: editor hover, completion lists, inspectors, the properties panel beside the canvas. A docs site is another building — a new tab, a new search for the component name, a new version check. Guidance at the point of use is more likely to be read not because the sentences are better, but because the cost of reaching it is folded into the task already underway. The same paragraph on a site waits until someone remembers to go and look.

In-context is not the whole site stuffed into a tooltip. It is the few sentences visible while the hand is still on the call: this prop should not be on, this combination breaks, here is a runnable example. Long form can stay on the site; the point of use is responsible for keeping the person in the original task long enough to finish the critical lines.

Why it happens

Working memory at the call site is already full of the shape of the interface. Opening a site inserts a new task: find the right component, the right version, the right paragraph, then carry the result back to the editor. Each step can be interrupted, so “look later” becomes “never look”. Hover and completion share the screen with the caret; reading happens before the decision is committed, before misuse is code.

Sites also drift in version: a bookmark may be newer or older than the installed package. In-context docs generated from the same source and shipped with the package show the guidance for this version. Readership is decided by “how much farther”, not by how many pages were written.

Where it stops holding

The point of use cannot hold decisions that need several components in view at once (page-level information architecture, responsibility across components); those still require leaving the call for long form. Pure visual exploration with no code caret lives in the design tool’s inspector; editor hover cannot help. Offline environments or those without a language service have no in-context channel, and the site is the only source. Pasting a whole chapter into a tooltip turns the point of use into a second site; reach cost returns as scrolling.

Applying it

• Put the sentences that must be known at the call (prop meaning, mutual exclusion, dangerous combinations) into type annotations, completion detail, and the inspector, published from the same source as the component.
• Keep on the site only the comparisons and background that will not fit in-context, and from the point of use link to this version of the long form — never a versionless portal URL alone.
• Measure whether the in-context channel is reached: completion detail showing, hover hitting the current symbol — not only site pageviews.
• How to check: ask someone new to the component to make a real call, with the docs site forbidden. If hover and completion alone steer them around a known misuse, in-context is working. If they must search the site to learn that one prop must not be opened with another, the critical sentence is not at the point of use. Then compare version stamps of the same sentence on the site and on hover; a mismatch means the in-context channel has already broken.

Related

• Same group: R1.12.2 Examples must run; static screenshots drift from the implementation · R1.12.3 Documentation ownership is bound to the component's change flow
• Adjacent: R1.04 Usage guidelines · R1.06 Contribution and governance
• Search terms: in-context usage guidance · docs at point of use · hover docs