Help and Documentation
Aim for a product that needs no explanation, then write help for the cases where that is impossible.
Definition
Nielsen's tenth heuristic. It is better if the system can be used without documentation, but help may be necessary. Any such information should be easy to search, focused on the user's task, list concrete steps, and not be too large.
Expert heuristic. A review criterion developed by practitioners. Useful and widely taught, but evaluated by judgement rather than measurement.
On this plate
Reach for this when
- Designing complex or unfamiliar domain features.
- Reviewing support volume and help centre analytics.
- Deciding between explaining and redesigning.
- Support volume is concentrated on one screen and the team is about to write a guide.
Common mistakes
- Documentation used as a patch for design problems.
- Help organised by feature rather than by task.
- Tours that interrupt before the user has a question.
Help is a signal, not just a deliverable
A help article that gets heavy traffic is usually pointing at an interface problem. Treat your support search log as a usability backlog: the top ten queries are the top ten things the product fails to explain by itself.
That does not mean help is a failure. Complex domains legitimately need explanation, and documentation for genuinely complex capability is a feature.
Layers of help, cheapest first
- 1.Self-evident design: the control explains itself through label, placement and affordance.
- 2.Inline hints: persistent helper text under a field, shown before the mistake rather than after it.
- 3.Contextual help: an information control that expands in place, without leaving the task.
- 4.Task documentation: a searchable article scoped to one job, with steps and screenshots.
- 5.Human support: escalation with the context already attached.
Do
- Keep help in context, so the user does not lose their place.
- Write for the task, not for the feature. Users search for what they want to do.
- Include the exact interface labels in the article so search finds them.
- Track help searches that return nothing, since those are unmet needs.
Do not
- Use a product tour to compensate for an unclear interface.
- Bury help behind a chat widget that requires waiting.
- Write documentation organised by your internal architecture.
Layers of help, and when each is the right one
| Layer | Right when | Wrong when |
|---|---|---|
| Clearer label or field hint | The confusion is about one control | Never wrong. Try this first |
| Inline explanation next to the work | A concept needs one sentence | The explanation is longer than the task |
| Tooltip or info icon | Supplementary detail, safe to miss | The content is essential, or the device has no hover |
| In-product guide | A multi-step task done rarely | Used as a substitute for a coherent flow |
| Help centre article | Depth, edge cases and search traffic | It is the only place the answer exists |
In practice
- i.
Inline help beats a help centre trip
Complex formsAn expandable explanation next to a tax status field keeps the user in the flow. Sending them to a help centre article loses a measurable share of them permanently.
- ii.
Support search as a backlog
Product operationsThe most searched help topic in a product was how to change the billing email. That is a navigation problem dressed as a documentation need.
- iii.
The help article that was a missing label
Reading support as a backlogThe most read article in the help centre explained what one field meant. Renaming the field retired the article, which is the outcome a help centre should be trying to produce.
Local chart
HEUR·010 · Region I · Grid A1
This entry and the entries it is stated to connect with. Each line is labelled with what the connection means.
Sources
Where a source establishes something narrower than the popular reading of it, the note says so.
- [1]
10 Usability Heuristics for User Interface Design
J. Nielsen, Nielsen Norman Group, 1994, revised 2020
Continue from here
Each link says what the connection is, so you can tell a principle from an alternative from a thing people mix this up with.
Why this works
The reasoning this entry rests on.
- Curse of KnowledgeBIAS·008 · Cognitive bias
- Paradox of the Active UserPSY·007 · Psychology
- Spacing EffectPSY·008 · Psychology
Applied through
Where this shows up as a concrete interface decision.
- TooltipCMP·013 · Component
- Design System DocumentationSYS·003 · Design system
- Empty StatesPAT·010 · Pattern
- OnboardingPAT·014 · Pattern
- Product AnalyticsRES·010 · Research method
- Content DesignWRT·004 · UX writing
- MicrocopyWRT·001 · UX writing
- Tooltips and Inline HelpWRT·015 · UX writing
Related concept
Connected closely enough to change how you apply this.
- Match Between System and the Real WorldHEUR·002 · Heuristic
- DiscoverabilityPRIN·005 · Principle
- Progressive DisclosurePRIN·003 · Principle