Info links allow users to switch between the help panel and the tutorial panel when a tutorial is active. Switching to the help panel doesn’t dismiss the tutorial.
Hands-on tutorials logic
Hands-on tutorials keep track of the status of tasks, not progress of individual steps
Each tutorial is composed of tasks, and each task is composed of steps. A task is achieved when users complete a series of steps.
Task - Creating a resource
Step - Naming the resource during resource creation
The hands-on tutorials pattern relies on page level validation for validating data on the page and surfacing an error message if needed
For example: When a required field is left empty.
The status of each tutorial is either pending or completed. If users dismiss a tutorial before finishing it, its status will be tracked as pending.
Whenever a new tutorial is introduced, keep the tutorial panel open by default
Display the tutorial panel as open by default whenever a new tutorial is introduced. The panel should remain open on all pages, until manually closed. Once closed, the panel should remain closed.
When a tutorial is launched, keep the tutorial panel open through all relevant pages as users move through the workflow.
When first introducing the tutorial panel, add a “-new” label to the tab header and keep it for 30 days. See the guidance for announcing new features.
Additionally, add the “-new” label to the title of any new tutorial and keep it for 30 days.
An open tutorial panel with the “-new” label to indicate that this is a new feature.
Enable different configurations than the recommended ones in tutorials
Don't prevent users from selecting configurations that are different from the tutorial's recommendation. Instead, inform users about potential consequences, if any.
In general, allow users to select configurations that are different from what is recommended, and still proceed with the tutorial. There might be some instances where selecting a non-recommended configuration can prevent users from achieving the goal they want. In such a case, add a warning alert to the annotation popover to communicate potential consequences.
Don't add the warning alert for steps where selecting a non-recommended configuration doesn't affect the end goal.
A warning alert within an announcement popover.
Key UX concepts
Hands-on tutorials are not a replacement for the help system
Hands-on tutorials serve the specific purpose of providing actionable suggestions at decision points in a particular workflow. Any help content that relates to explaining general terms or concepts within the interface should be clarified by using the elements of the help system. Information presented in the hands-on tutorials should require minimal effort to read and act upon. See the guidance for onboarding.
Don’t introduce tutorials for very simple flows
Tutorials create additional clicks and can be more obtrusive than helpful if used for very simple flows. Tutorials should be introduced to improve comprehension and add value that can’t be achieved with the use of existing UI elements in complex flows.
If a tutorial includes a step that needs to be completed in another service, provide guidance for users to navigate to the correct service and return back to the tutorial after the step is completed. The underlying service should open in a new tab.
When introducing multiple tutorials, have the most relevant tutorials at the top of the list, with their cards expanded by default. Have all other tutorial cards collapsed at the bottom of the list.
Surface hotspots only when a tutorial is active. When the tutorial is dismissed, remove the hotspots and display the tutorials list state.
Avoid repeating concepts that should be handled by other UI elements on the page. See guidance for help system.
Don’t display multiple annotation popovers at once. The previous popover closes when a new one is opened.
Avoid providing guidance for optional actions within the flow, unless completing that action can be beneficial to the user’s overall comprehension of the service.
Don't hide tutorials that can't be launched yet. Use an alert to communicate prerequisites for launching the tutorial instead.
General writing guidelines
Keep labels and descriptions clear and concise.
Use parallel sentence structure.
Use sentence case for all text. Don’t use title case.
Use terminal punctuation (periods, exclamation points, question marks).
Use present-tense verbs and active voice wherever possible.
Don't use "please," "thank you," or Latinisms such as "e.g.," "i.e.," or "etc."
The annotation context is an invisible layer on top of the interface. It tracks the progress of a launched tutorial and feeds dynamic content to the Tutorial panel in Hands-on tutorials. It also renders annotation popovers and hotspot icons.