Overview
Including embedded guidance on UI elements is an efficient way to avoid user errors and to educate them along the way, as they use the product. It includes short instructions or explanations in the UI that guide users, so they stay on the right path to complete a task. This helps users achieve their goals faster, because they don’t need to stop what they are doing and leave the application to search for information elsewhere.
<div> <div>Embedded Guidance</div> <div>Messaging</div> </div> <div> <div> <p>Always visible on the UI and doesn't require any action from users or a system to make it appear or disappear.</p> <p><strong>Note:</strong> If the guidance benefits only a sub-population of the target user groups, however, it can be displayed in a popover that can be opened by users.</p> </div> <div>Triggered by user interactions or by events that occur in the system</div> </div>
- Types of embedded guidance and examples
- Best practices for each type of embedded guidance regarding display and the UI text
Usage
- briefly explain a feature, so users can gain a high-level understanding of the purpose it serves (if detailed information is required for complex features, include a link to online documentation).
- provide an instruction for the next user action, so users don’t lose time.
- describe the outcome of the actions the user is about to take, so users feel empowered to take the action or not.
information
NoteAlways include embedded guidance text on empty states.
- You want to provide information in reaction to a user action during a specific workflow. For example, selects a date for scheduling which is not valid. To display information triggered by user actions or system events, use Messaging.
- You want to provide comprehensive guidance that won’t fit into the UI. For example, an explanation of the values users can specify to set parameters. For this kind of case, use Web Assistant instead.
Embedded Guidance can be delivered in different formats based on its importance and granularity.
<div> <div>Type</div> <div>Description</div> <div>Example</div> </div> <div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fr%2FPHjx7Tox2dPw1GOuic5NKdgd9otiZTaWIXg77dqtt9k">General Information</a></div> <div>Basic description about a target (object, page, or section)</div> <div>Educate the user about the purpose of a feature or what steps they can take to start using it.</div> </div> <div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fr%2FABnYWyKe2hBiuaz48kJfUxcuQo1ljyYR8w_iU-5328E">Key Information</a></div> <div>Important information that users need to pay attention to.</div> <div>Inform the user that the selected object has been modified or that it expires after a specific time.</div> </div> <div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fr%2FRbUECEllfaWYK9CF6aGzwGVUdlFzs8mlNgELzn101b8">Warnings</a></div> <div>Critical information about the consequence of an action that assists users to take a decision of a large impact.</div> <div>Warn the user that if they leave the page without saving it, they will lose their latest changes.</div> </div> <div> <div><a href="https%3A%2F%2Fwww.sap.com%2Fr%2F2bjYD05fYS75ibKNAQCt6jylYrUDoVpLpJzIQ6jeiak">Supplementary Information</a></div> <div>Additional and contextual descriptions about a target, which experienced or expert users may not require.</div> <div>Explain the different functions available for formulas.</div> </div>
General Information
Use a text to display general information that simply explains a page or items in the page.
Best Practices
How to Display
- Place the guidance close to the target to which it relates, so that users can easily relate it to the correct target.
- Consider typographic aspects even in responsive views. For example, line length, or orphans.
- You can mix different text styles in the guidance to emphasize important things and improve readability. However, do not overuse different text styles, because this will visually differentiate the guidance too much from the other UI elements.
How to Write
<div> <div>Writing Best Practice</div> <div>Example</div> </div> <div> <div>When a feature could be unclear to users, explain what the feature enables users to do.</div> <div>“SAP Business Technology Platform Cloud Connector allows you to connect to on-premise data sources from cloud applications.”</div> </div> <div> <div>When several options are possible for the user to make a choice, detail the criteria they should consider before they make their choice.</div> <div>In the section “Add a Responsive Page” add the general information: “To build a story for users using mobile devices, select Responsive Page.”</div> </div> <div> <div>For input fields, where syntax is not controlled by the UI, provide users with instructions or an example.</div> <div>“Enter email address of each recipient separated by a comma.”</div> </div> <div> <div>Use “you” to address your users, as though the software UI is speaking to them directly.</div> <div>“You can create and manage users here.”</div> </div> <div> <div>Keep sentences short to convey just the most important information. Add a link to more detailed information that less experienced or expert users might need, if appropriate.</div> <div>Integrate SAP Business Technology Platform Open Connectors with SAP Analysis Cloud to connect to third party data sources powered by Open Connection. For more information see <a href="https%3A%2F%2Fhelp.sap.com%2Fviewer%2F00f68c2e08b941f081002fd3691d86a7%2FLATEST%2Fen-US%2Fc2789fc8f9af44f186a20a4467186e3c.html">Open Connectors</a>.</div> </div> <div> <div>Don’t repeat button labels or section headers in the embedded guidance text.</div> <div>If the section header says “Welcome to the Data Builder,” don’t start your embedded guidance text with “Welcome to Data Builder! Create new data providers, upload and integrate data here.”</div> </div>
2
do
false
dont
false
Key Information
Use Information message strips to highlight additional important but not critical information that users need to know regarding the target. For example, a system recommendation. The user is not obliged to take any action.
Best Practices
How to Display
- Place the guidance above the target. If the target is one of many options, place its guidance below the target.
- The guidance should always be visible to inform users.
- Display the Information icon with the guidance to ensure accessibility. (showIcon: true, type: Information)
How to Write
- Keep the message short. Strip out unnecessary words that could distract the user or not clarify the meaning of the text.
- Make users aware of information that might prevent a problem, especially when making choices.
- Give users the information they need to take any necessary decisions.
2
do
false
dont
false
Warnings
Warning messages help prevent user errors. Use a Warning message to alert the user of a condition that might cause a problem in the future. For example, configurations that cannot be changed later may require a significant effort by users.
warning
NoteWhen a warning is required prior to the user confirming an action, use Messaging.
Best Practices
How to Display
- Place a guidance above a target. If a target is one of many options, place its guidance below the target.
- The guidance should be always visible to warn users.
- Make sure to show an icon with the guidance for accessibility. (showIcon: true, type: Warning)
How to Write
- Describe the problem concisely, keeping the text as short as possible. Explain the future impact and provide details of any recommended actions the user can take to minimize risk.
- Address the information to the user, using “you.” For example, “If you leave this page any unsaved changes will be lost.”
- Order the information in a logical manner, explaining first the cause and then the outcome.
2
do
false
dont
false
Supplementary Information
To provide contextual and detailed information that is necessary for some users, but not for all users, use an Information popover so that content is only visible when users want to click on the Information icon next to the target.
warning
NoteInformation messages of this type require no action from the user.
Using popovers keeps the UI uncluttered and still provides necessary information to less experienced users. For example, new users to analytics may not understand the term “Measure” when asked to select a measure from a list. You can use an Information popover to explain the concept of measures to these users. Because the explanatory text is not permanently displayed, it doesn’t clutter up the UI and experienced users don’t need to pause to read it.
Best Practices
How to Display
- Place a button (sap-icon://message-information) to trigger an information popover close to the target item. When a user clicks the button, an information popover usually shows up on the right side of the target so as not to block other content in the screen.
- When you format the content, consider its readability because the text is displayed in a relatively small popover.
- Avoid using an information popover over another popover. This can clutter the screen with different depths and confuse users where to click.
guideline
TipUse Web Assistant popovers when Web Assistant is available in the product.
warning
NoteIf the information needs to be shared with all users, then use another type of embedded guide, see Usage.
How to Write
- Supplementary information must provide additional value to the user; it mustn’t just repeat the UI texts that are always visible.
- The text needs to either explain a concept or instruct the user what they need to do next in the workflow. For example: UI Label is “Configuration Title”; supplementary information popover text is “This title is used in the application header at runtime and will be visible to end users.”
2
do
false
dont
false
Resources
Support
If you have any questions or feedback about this page, please contact our team. For further information and questions in regards to the Design System, please visit the DNA Design SharePoint.