In-App Help and Guidance Patterns
Overview
User guidance in Salesforce should be treated as a product feature, not post-go-live documentation cleanup.
This guide covers practical options and tradeoffs for help systems across:
- inline help,
- contextual prompts,
- persistent documentation hubs, and
- operational training assets.
Consensus Best Practices
- Start with field-level help text quality before adding advanced tooling.
- Use lightweight contextual guidance for high-friction workflows.
- Keep canonical long-form docs in one place (Confluence/SharePoint/Docs site).
- Favor solutions users can reopen on demand.
- Avoid guidance formats that disappear permanently after first dismissal.
- Treat help content ownership as an ongoing operational role.
Guidance Layers
Layer 1: Native Field and Page Guidance
- Field help text for all critical fields.
- Clear section names and layout grouping.
- Validation messages that explain correction steps.
Layer 2: Contextual Prompts
Use for new-process rollouts and behavior change campaigns.
- Suitable for temporary nudges.
- Not sufficient alone for complete help systems.
- Must be paired with persistent docs for reference.
Layer 3: Persistent Help Surface
Examples:
- Utility bar help panel,
- rich text component with links,
- custom tab/web tab for documentation.
Goal: users can access help whenever needed, not only when a prompt appears.
Layer 4: Full Documentation System
For complex orgs, maintain searchable docs with:
- role-based quick-starts,
- task playbooks,
- troubleshooting guides,
- release notes with user impact.
Selection Framework
Choose based on need:
- Need quick reminder -> contextual prompt.
- Need always-available reference -> utility/help tab + docs site.
- Need process walkthroughs -> guided flows or dedicated training modules.
- Need deep operational support -> full knowledge base + support model.
Common Failure Modes
- Building flashy prompt systems while field-level help remains poor.
- No owner for content freshness after release.
- Guidance that cannot be reopened by users on demand.
- Multiple conflicting documentation locations.
Implementation Checklist
- Define help content owner(s) and review cadence.
- Apply or update help text for top-used objects.
- Publish role-specific task guides for core workflows.
- Add persistent help entry point in Lightning UI.
- Track support ticket themes and update docs accordingly.
Sources Used
Knowledge/Jodie Miners/TDD-Help.md- Catalog of in-app guidance/documentation options and practical constraints