Onboarding & In-App Help Strategy
A framework for building usable and accessible help systems.
Summary: Decades of usability and accessibility data have shown that many common onboarding and in-app help design patterns just don’t work well in the real world. This post details a reusable framework for how best to display help content in complex applications.
I recently wrote a document to help define a reusable set of UX best practices for product onboarding and in-application help. This week’s post is a generalized version of that document that you can use in your own day-to-day work.
My goal was to make help content decisions more strategic across products, platforms, and teams, so this guidance is intentionally technology- and domain-agnostic. Everything in this week’s post focuses on widely accepted usability best practices, helping users complete real world tasks, and giving users guidance at the moment they actually need it.
And I think this matters because a lot of UXers and product teams don’t seem to know about these best practices anymore. Products like Pendo make it easy to add UI elements into apps, and I worry that many UXers have started favoring these quick-win methods over foundational user-centered principles.
If you need a starting point for discussion with your team, I encourage you to share this post. My hope is this info is especially useful for UXers trying to create more consistent guidance across teams without turning every onboarding or help experience into a maze of popups, tours, and misunderstood help widgets.
⚠️ Disclaimer: This is meant to be used as a reference guide, so you’ll notice that a few ideas repeat across some sections.
Core Strategy Principles
Keep guidance contextual and just-in-time. When possible, information should appear at the moment a user needs it to make the next decision or take the next action. Avoid front-loading instruction that users must remember for later interactions and decisions.
Require only what is necessary up front. Use step-by-step onboarding only for information the system genuinely needs in order to function, or for required security, compliance, or activation steps. Everything else should be deferred until it becomes relevant and displayed just-in-time in the workflow.
Make the next action explicit. Each step should make it obvious what the user is expected to do next. The goal is not the fewest possible words. The goal is the minimum amount of text needed to make the next action or decision clear and explicit.
Show only what is relevant to the current user and context. Where possible, the experience should adapt based on role, permissions, product access, workflow stage, and device context. Users should not be exposed to features, instructions, or decisions that do not apply to them.
Prevent errors and make recovery easy. Onboarding and self-serve setup or data management should reduce the chance of mistakes through clear structure, validation, and review processes. When errors do occur, the system should make correction options straightforward, visible, and explicit.
Keep help inside the workflow whenever possible. The primary support strategy should be built directly into onboarding, self-service configuration, and the product experience itself. It should not depend on separate documentation systems, long text-heavy help panels, or standalone training content.
Help & Onboarding Specifics
Use wizards selectively. A wizard is appropriate when the task needs a clear sequence of required setup steps. It should not be used to force optional configuration, introduce broad product education, or present every available feature at once.
Organize around decisions and tasks, not system structure. Each onboarding step should support one main action, one main decision, or one coherent group of closely related inputs.
Keep progress visible. Required setup should be broken into clearly named steps so users understand where they are, what remains, and what has already been completed.
Defer nonessential setup. Optional details, secondary preferences, and lower-priority configuration should not be added to upfront onboarding steps. These items should be introduced just-in-time, in context, when they become relevant to the user’s workflow.
Use progressive disclosure carefully. Show the information most users need directly on the screen. Following the 80/20 Rule, the default view should include the guidance most users need to move forward without extra clicks. Secondary details, exception paths, and less common cases can be placed behind a clearly labeled expand option or another explicit interaction. Do not hide essential guidance by default.
Design for exceptions without breaking the primary workflow. Even when the underlying onboarding work is not literally linear, the experience should still impose a clear sequence whenever that creates a more understandable path through setup. That sequence should accommodate all valid scenarios without blocking users whose path differs from the common case. (This could be implemented using progressive disclosure in the frontend, supported by conditional logic in the backend.) The default flow should be optimized for the 80/20 path, while less common cases can be handled through branching, progressive disclosure, or guided exceptions inside the overall sequence.
Support save and return at all cost. Users should be able to pause and resume onboarding without losing work or losing their place when the process is likely to span multiple decisions or sessions.
Validate in place. Errors and warnings should appear close to the relevant UI control or user action, using plain, user-centered language with explicit guidance on how to correct the issue. However, first look for all possible methods to avoid system errors in the first place. (Allow the system itself to do the bulk of the work.)
Provide a review point before commitment. Users should have a chance to confirm important choices before activation, submission, or any downstream consequence that is difficult to undo.
Confirm irreversible actions. Any choice that is irreversible, or that would require manual support intervention to correct, should trigger an explicit confirmation modal that clearly states the consequence.
End-User Onboarding Best Practices
In general, end-user experiences should focus on fast, confident entry into core product use. The product should not assume that new users want a tour, a lesson, or a lengthy profile setup process before they can begin.
Minimize first-run friction. Only the steps required for access, security, compliance, or immediate product use should appear up front.
Avoid forcing completion of nonessential profile or preference fields. If information can be added later, it should be deferred and requested just in time, and only when it becomes useful to the user.
Introduce features at first meaningful use. If a user is about to encounter a task or feature for the first time, contextual instruction may be appropriate when delivered just-in-time.
Tie guidance directly to the relevant interface components. When a prompt or instructional message appears, it should point to the exact UI control or choice the user is working with and explicitly explain what to do now in context.
Use the same standards on mobile. A mobile experience should follow the same just-in-time and contextual model. For accessibility and usability reasons, do not rely on hover behavior, hidden affordances, or dense text patterns that are difficult to use on smaller screens.
System Admin Onboarding Best Practices
System admin onboarding should be treated as a guided setup experience, not a general product introduction. These users are usually configuring important parts of the system, making decisions that affect other users, and managing settings that may have downstream consequences. The experience should help them move through required setup tasks with enough structure, context, validation, and review to feel confident before anything is activated or applied.
Prioritize structured setup over broad education. The setup experience should lead admin users with setup responsibilities through required decisions and setup activities in a deliberate sequence instead of expecting them to learn the system through large amounts of introductory content. Even when the underlying work is not fully linear, the experience should create a clear sequence if one can support all necessary scenarios. That sequence should be designed to work for all such users, while being optimized for the most common (80/20) paths wherever possible.
Keep the experience focused on the task at hand. Do not expose unrelated features, settings, or reference material during setup or configuration tasks if possible.
Make system state clear. Admin users should always be able to tell where they are in the setup process, what has been completed, what is in progress, what still needs review, and where action is required. Also consider including additional push notifications to encourage progress where possible.
Design for confidence before activation. The experience should favor review, preview, validation, and confirmation over workflow speed, especially where configuration choices have impactful downstream effects.
Support error prevention and correction as part of the workflow. The experience should assume that some information will need to be revised during setup. Editing, revisiting earlier decisions, correcting errors, and continuing forward should feel like part of the intended process and be explicit.
Use just-in-time embedded help at decision points. Admin users should receive concise guidance where choices are made, especially during setup moments that require interpretation, review, or error correction. This is especially important for bulk setup actions. Guidance should use language framed from the user’s task perspective. The system should not send them away to search through general documentation to understand a required setup decision if possible.
Respect role and permission context. Different admin user segments should only see the configuration choices, instructions, and follow-up guidance that apply to their responsibilities where possible.
Help & In-App Guidance Best Practices
Help should be treated as part of the product experience, not as a separate system. The goal is to give people enough information to move forward from the screen they are already on, without requiring them to stop, search, and interpret a large external help system.
Make embedded guidance the default. The first choice should be inline instructions, targeted helper text, well-written empty states, clear labels, and task-level prompts placed within the workflow.
Write from the user’s point of view. Help text should be framed around what the user is trying to do, what action to take, and what happens next. It should not be written from the system’s perspective.
Keep required help visible. If most users need a piece of guidance in order to proceed correctly, that guidance should appear on the face of the interface. It should not be hidden behind a click, tooltip, or icon-only control.
Use progressive disclosure only for secondary help. Expandable content is appropriate for extra explanation, edge cases, definitions, or deeper detail that only a smaller portion of users will need. All uses of progressive disclosure should be accessed via an explicitly labeled UI component.
Avoid icon-only help patterns. All help-triggering controls should be explicitly labeled. For accessibility and usability reasons, do not rely on question-mark icons or other symbols alone to communicate that useful information is available.
Do not put essential help in tooltips alone. Tooltips and similar patterns may support supplemental explanation, but they are not strong enough to carry required instructions or critical decision support. Also, keep in mind that hover-only controls are deeply inaccessible in all UI context and inherently unusable on mobile.
Use empty states as guidance moments. When a screen or area has no content yet, the empty state should explain what belongs there and what the user can do next.
Use error states as guidance moments. Messages should explain what went wrong, what the user can do now, and whether the issue can be resolved in the product or requires support.
Treat external help systems as secondary. A separate documentation system may still exist, but it should act as backup reference material. It should not be the primary method for explaining how to complete onboarding or common in-product tasks.
Design content for reuse across contexts. Help content should be modular enough to be placed near relevant tasks across the product rather than stored only as long, standalone pages.
Example Patterns to Avoid
Avoid showing the full complexity of the system too early. Sometimes complex products still need sequencing. The right response to complexity is guided structure and contextual disclosure, not exposure of every option at once. See Wizards: Definition and Design Recommendations, UI: Proper Indicators for Hidden Elements, and Design for Optimal Experience.
Avoid onboarding carousels or introductory tours. Do not present users with a sequence of pop-up slides or feature-overview screens at first login as the primary onboarding method. These patterns usually ask users to remember abstract guidance before they have a real task or decision in front of them. See Carousel Interaction Stats, Onboarding Tutorials vs. Contextual Help and Mobile Tutorials: Wasted Effort or Efficiency Boost?.
Avoid broad first-run walkthroughs that explain the whole interface. Even when step-by-step guidance points at specific UI elements, this pattern is often difficult for users. It can interrupt task flow, appear out of context, and force users to memorize instructions they can’t easily recall or apply when needed. See Onboarding Tutorials vs. Contextual Help, Instructional Overlays and Coach Marks for Mobile Apps, and Help and Documentation (Usability Heuristic #10).
Avoid global “help” entry points as the main solution. A global help button, floating chatbot, generic right-side help pane, or detached knowledge base should not carry the primary burden of teaching the workflow. These patterns can be useful as secondary support, but they often force users to leave the task, search for the right answer, interpret generic content, and then apply it back to the screen they were already using. See Help and Documentation (Usability Heuristic #10) and Onboarding Tutorials vs. Contextual Help.
Avoid non-contextual help panes. A right-side help panel can be useful when it is tied directly to the current screen, task, role, or decision. It becomes much less useful when it acts like a generic documentation drawer that displays broad reference content without knowing what the user is trying to do. Help should reduce interpretation work, not add another layer of searching inside the product. See Help and Documentation (Usability Heuristic #10) and Onboarding Tutorials vs. Contextual Help.
Avoid unlabeled icons and ambiguous controls. If a control is important enough to influence comprehension or decision-making, it should be labeled clearly. Do not hide required guidance behind a “?” icon, icon-only button, hover-only tooltip, or any other symbol that users have to discover, interpret, and activate before they know useful help exists. See Icon Usability and Tooltip Guidelines.
Avoid putting essential help in tooltips alone. Tooltips and similar patterns may support supplemental explanation, but they are not strong enough to carry required instructions or critical decision support. They are easy to miss, often depend on hover behavior, and can create serious usability and accessibility problems on mobile, touch devices, and keyboard-only workflows. See Tooltip Guidelines, UI: Proper Indicators for Hidden Elements, and Design for Optimal Experience.
Avoid walls of text. Large blocks of explanatory copy are difficult to scan and are usually a sign that the content is not tightly aligned to the decision the user must make. See Plain Language Is for Everyone, Even Experts and F-Shaped Pattern of Reading on the Web: Misunderstood, But Still Relevant (Even on Mobile).
A Pattern That Works
At a high-level, onboarding and help should make the next step clear at the moment it matters. Required setup should be structured and guided. Optional setup should be deferred. Help should be embedded, explicit, role-aware, and written from the user’s point of view.
This approach is especially important for complex, role-based products. The more the product can tailor onboarding and guidance to the user’s role, permissions, and current task, the more intuitive and self-sufficient the digital experience becomes.
UX Strategy for Key Workflows
This section translates the onboarding and in-application help principles into concrete experience direction for high-value workflows across products and platforms. The consistent approach across workflows is to keep the primary screens task-focused, introduce complexity only when it becomes relevant, make the next action explicit, validate in place, provide review before commitment, and keep required help visible within the flow.
Reusable Building Blocks
Guided task flows (wizard only when required): Use step-by-step guidance when there is a strict sequence (e.g., review → confirm → submit). Otherwise, keep users on a single primary screen with clear sectioning and strategic use of conditional logic and progressive disclosure.
Workflow checklists + system state: A persistent checklist showing what’s complete, what’s blocked, what’s next, and what requires attention (especially for multi-session work).
Strong empty states: When there’s nothing to display yet, explain what belongs here and provide one clear call to action (CTA) to get started.
Inline validation and guardrails: Validate as users type or select, keep errors near controls, and explain how to fix issues in plain language. Reserve blocking errors for truly blocking constraints.
Review/confirm screens for consequential actions: Provide a preview of impacts (what changes, effective timing, downstream consequences) before final submission or activation.
Contextual help at decision points: Short helper text, definitions, examples, and “what happens next” messaging embedded in the flow. Use progressive disclosure for edge cases; avoid icon-only help.
Save-and-return + drafts: Support long or multi-stakeholder tasks with drafts, autosave, and clear “resume where you left off” entry points.
User role- and permission-aware tailoring: Show only actions and guidance relevant to the user’s role, access level, and workflow stage.
Notifications: Use in-app and (where applicable) email notifications to drive completion for time-bound or multi-session workflows (missing items, pending approvals, approaching deadlines).
Conclusion
In practice, a lot of teams do not follow these guidelines. Sometimes it is because the product is complex. Sometimes it is because onboarding gets treated like a communication problem, a training problem, or a feature-adoption problem. And sometimes it is because patterns like tours, popups, floating chatbots, generic help panes, and “?” icons feel like easy solutions when a complex workflow is hard to design for across multiple teams.
But the usability and accessibility data gives us a pretty clear reason to reconsider. Required guidance works better when it is visible, contextual, and tied to the task a real user is trying to complete in the real world. Users should not have to remember instructions from five screens ago, hunt through generic help content, or discover hidden guidance before they can move forward.
So if your team is using this post as a starting point, I hope it helps you push for onboarding and help decisions that are more grounded in evidence, more consistent across products, and more respectful of how people actually use software in the real world. Thanks for reading!
Citations
Baymard Institute, UI: Proper Indicators for Hidden Elements
Interaction Design Foundation, Design for Optimal Experience
University of Notre Dame, Carousel Interaction Stats
Nielsen Norman Group, Onboarding tutorials vs. contextual help
Nielsen Norman Group, Wizards: Definition and design recommendations
Nielsen Norman Group, Instructional overlays and coach marks for mobile apps
Nielsen Norman Group, Help and documentation (Usability Heuristic #10)
Nielsen Norman Group, Mobile tutorials: Wasted effort or efficiency boost?
Nielsen Norman Group, Plain language is for everyone, even experts
Nielsen Norman Group, Tooltip guidelines
Nielsen Norman Group, Icon usability
Nielsen Norman Group, F-Shaped Pattern of Reading on the Web: Misunderstood, But Still Relevant (Even on Mobile)