Documentation
Robust, clear documentation is an essential aid to using digital products. However, consulting static documentation removes the user from the product and requires an expensive context shift. Where possible, we should provide documentation at the point of use. When necessary we should link to static documentation.
Control Labels
Often screen functionality can be documented with no special treatment. Rely on control labels when:
- The task is familiar to nearly all users
- An action is reversible or ephemeral
- An action is a core part of the interaction loop
Inline Text
Sometimes a short blurb can set context and help the user parse the remainder of the screen. Include brief inline documentation (a paragraph or less) when:
- Our implementation of a feature differs from the industry standard
- Introducing a new workflow which is infrequently used
- An action may have side effects which are not top of mind for the user
- Confirming a destructive action
- Reporting that an error has occurred
Inline documentation should typically be presented as regular text. This allows veteran users to scan past introductory text and quickly start on workflows. There are a few exceptions:
- Use an informational alert when a feature is error-prone, unintuitive, or produces side effects that would not be obvious to a typical user. Ideally the system itself should behave in a predictable way, but technical or schedule constraints occasionally require that we paper over issues in the UI.
- Elevate informational alerts to warning alerts when these problematic features also carry high risk of damage to user data or system functionality.
Linking to Documentation
Link to static documentation when:
- The rules governing an action are too complex to explain in a paragraph
- Using a feature requires unusual or specialized knowledge
- The user must perform actions outside our UI (configuring other software, gathering credentials, creating an account, etc)
- Remediating an error requires unstructured troubleshooting