Designing In-App Help

This issue is about how a product explains itself to the people using it — the in-app help that tells someone what a page is for, what they can do on it, and what its unfamiliar terms mean. The conventional approach is to hang a small tooltip off each confusing label. That feels thorough, but it scatters explanation across dozens of hidden surfaces, none of which a user can reliably find at the moment they need it. The problem compounds in products with real domain vocabulary — compliance terms, insurance language, industrial jargon, anything where the words carry precise meaning — because the people who need the help most are often outside parties who never absorbed the internal shorthand.

I recently went through how the major design and accessibility authorities approach this, and what stood out was how closely they agree. Nielsen Norman Group, the GOV.UK content team, Shopify Polaris, Atlassian, Salesforce, Carbon, and the W3C all point in the same direction. What follows is a summary of where that consensus lands. The short version is that explanation belongs in a single help panel the user opens when they want it, backed by one shared glossary — rather than spread thin across per-label tooltips.

Why tooltips can't carry essential help

The starting point is that a tooltip is a supplementary surface rather than a primary one. NN/g states this plainly: information vital to task completion should not go in a tooltip, and neither should instructions or constraints. The reasons are structural rather than stylistic. Tooltips are hard to discover because they usually lack a visible cue. They don't work on touchscreens, where there is no hover. And when they repeat what's already on screen, they become what NN/g calls "information pollution."

Design systems enforce the same boundary in their own component docs. Salesforce caps tooltip text at roughly 200 characters and forbids essential instructions or embedded HTML. Carbon draws a sharp line between a tooltip (hover-triggered, non-persistent, no essential content) and a toggletip (click-triggered, can hold richer content and links) — and is explicit that a tooltip should never carry essential task instructions precisely because it isn't persistent. The (?) info-tip variant gets a particularly direct rebuke from NN/g: essential instructions, constraints, and legal disclaimers should not be hidden inside one. Show that information inline instead.

None of this makes tooltips useless. They work well for clarifying an icon-only button or a single unusual field. The trouble comes when a tooltip is asked to explain what a page is for or what a regulated term means, because that places content the user genuinely needs on a surface that is, by design, the hardest to find and the easiest to miss.

Pull help versus push help

If not scattered tooltips, then what? The most useful distinction in the research is NN/g's framing of "push" versus "pull" help. Push help interrupts — the modal that fires on first load, the coach-mark tour the user didn't ask for. Pull help waits to be summoned. NN/g's guidance is to favor pull over push, to keep any proactive help short, and to make help "available without interfering." User-initiated overlays, they note, are less jarring than system pop-ups, and people are more likely to engage with help they requested themselves.

A slide-out help drawer is the natural home for pull help. It has room to explain a page's purpose, the user's workflow, and the vocabulary on screen — the three things tooltips handle worst — while staying out of the way until someone opens it. Carbon's toggletip is the small-scale version of the same idea; a drawer is simply the roomier sibling for page-level explanation.

Two patterns sit on either side of the drawer and complement it. Inline hint text is the right place for any genuinely essential per-field rule, like a format requirement, because it's always visible. And a linked knowledge base is the right home for deep reference material; the drawer should point to it rather than try to contain it.

The one pattern worth approaching with skepticism is the guided tour. The evidence against long linear tours is consistent if not peer-reviewed: vendor data suggests abandonment climbs steeply past the first few steps, and contextual, behavior-triggered guidance tends to outperform a fixed sequence. The exact numbers come from practitioner blogs and deserve a grain of salt, but the direction is consistent with NN/g's broader preference for contextual over upfront help. Where first-run orientation is genuinely wanted, a single contextual prompt tends to serve users better than a multi-step walkthrough.

Designing the trigger and the panel

A drawer is only as useful as it is discoverable, and discoverability is exactly where tooltips tend to fail, so the trigger that opens the drawer deserves careful attention. A reasonable approach is a persistent control in a predictable place — the page header works well — present on every page, so users only have to learn where to look once. It should be an actual button, labeled something like "Help" or "About this page," rather than a bare hover target. Carbon's disclosure semantics describe the right model: a button whose press toggles the panel.

Inside, structure every page's help the same way, so the format itself becomes learnable. A skeleton that holds up well: a sentence or two on what the page is for; a short list of verb-first steps for what you can do here; the key terms on this page, pulled from the shared glossary; and a "learn more" link out to deeper docs. Keep it scannable, front-load the keywords, and aim for roughly a seventh-grade reading level, which is Polaris's target and a good default for prose meant to be skimmed under mild stress.

It also helps to give users control over the panel: let them close it with Escape, an explicit ×, or a click outside, and default it to closed so that the help is available when summoned without being present uninvited.

A shared glossary keyed by stable code

If the drawer settles where help lives, the glossary settles whether it stays consistent over time. This is the part engineers will recognize most readily, because it is fundamentally a data-modeling decision rather than a content one.

The durable pattern is to key every term and its definition by a stable code, not by the label that happens to be displayed. Frontitude describes this as assigning each string a unique key and storing the copy separately from the code, so that a single edit propagates everywhere the term appears. The reason to key by code rather than by display string is the same reason you would not use display strings as database keys: rename the label and a string-keyed definition orphans itself silently, whereas a code-keyed one keeps resolving correctly. The same definition then renders identically in the drawer, in any inline glossary popover, and on a global glossary page, because all of them read from one record.

On top of the keyed strings sits a governance layer. Atlassian maintains an official vocabulary — a wordlist that defines each term, both what it means and the context it is used in, with one canonical word per concept. That is what structurally removes the most common source of terminology drift, which is several different words circulating for the same idea.

There's a tooling fork worth naming. Copy-management vendors sell this as a separate SaaS that syncs to your design tool. For most engineering teams, keeping the glossary in-repo as a versioned table or JSON file is the better trade — the same "key by stable code" benefit with fewer moving parts, living next to the data the terms actually describe. The principle is identical either way; only the storage location differs.

Explaining technical terms without simplifying them

In a regulated or technical domain, there is a temptation to simplify the vocabulary itself, and it is worth resisting. Terms like certificate of insurance or additional insured carry precise legal meaning, and softening them introduces error. GOV.UK's content team states the rule cleanly: technical terms are not jargon, and the requirement is simply to explain them the first time they appear. The approach that follows from this is to keep the correct term and make its plain-language definition one click away through an interactive glossary, and to expand acronyms on first use unless they are universally known.

This matters most for external users, who never had the chance to absorb an organization's internal fluency. For them, the drawer's "key terms" section together with a searchable global glossary acts as the bridge between precise internal vocabulary and a reader encountering it for the first time.

Keeping help in sync as the product changes

Help content tends to rot when it lives apart from the product it describes. The common remedy is to treat it like code: version it, review it in pull requests, and ship it in the same release as the feature it documents — the docs-as-code approach, kept in the same repository so that updates happen together. Because definitions are keyed by code, a continuous-integration check can fail the build on a missing definition or an orphaned term code, which moves "keep the help in sync" from a recurring manual chore toward a structural guarantee. Paired with light editorial governance — an owner who reviews new or changed terms against the vocabulary before they merge — this is what keeps drift from accumulating between cleanups.

Accessibility: building the drawer as a non-modal dialog

A help drawer is, structurally, a disclosure trigger attached to a dialog-like panel, and the W3C's authoring practices cover both in detail. The trigger should be a native button carrying aria-expanded and aria-controls. The panel needs an accessible name, supplied through aria-labelledby pointing at its heading. When the panel opens, focus should move into it, since otherwise screen-reader users have no signal that it appeared; Escape should close it, and focus should return to the trigger on close.

There is one design choice worth making deliberately. A help drawer is generally better as a non-modal dialog: it should not block the page behind it or trap focus, because the point is to let people reference help while they continue working. That means sending focus into the panel on open, allowing Tab to move back out into the page, and adding a focus trap only if the drawer is later made modal for some other reason. It is also worth honoring prefers-reduced-motion — replacing a large slide animation with a fade or an instant reveal for users who have asked for less motion. As the accessibility writing on this notes, a panel that fades in still communicates the change of state without risking the vestibular discomfort that large motion can cause.

How the pieces fit together

The individual recommendations reinforce one another. A discoverable, user-summoned drawer becomes the primary place explanation lives. Tooltips fall back to clarifying icons. Genuinely essential rules move into visible inline text. And underneath all of it, a single glossary keyed by stable code supplies every surface the same definition, governed by a small vocabulary and shipped alongside the code so that it does not quietly drift out of date.

It is worth naming one non-goal, because the same research that endorses the drawer also cautions against over-building it. NN/g's assessment is that an "intelligent" or adaptive help system usually costs more than it returns, and that a wrong prediction carries a real cost in user trust. Static, per-page, keyed content is cheaper, more reliable, and generally sufficient. The aim throughout is fairly modest: help that a person can find, trust, and understand. Most of what gets you there is simply putting the explanation in one discoverable place and keeping the vocabulary from drifting — which is less a matter of cleverness than of discipline applied consistently over time.