Teaching tips and in-app tours for onboarding users

Article
08/31/2023

A key element in educating users about Business Central pages and concepts is the tour. A tour is a sequence of teaching tips.

Teaching tips can be defined at the page level, the page teaching tip, and be followed by teaching tips at the control level, the control teaching tips. Both types of teaching tips are defined by the .AL properties AboutTitle and AboutText (or their multi-language versions), and an extension can overwrite teaching tips in the default version.

Page teaching tips

The primary purpose is to increase the user's chance of success with the page. So, the title and description of the page teaching tip should answer the following hypothetical user questions:
- AboutTitle: What is this page about?
- AboutText: What can I do with this page?
Teaching tips explain Business Central logic that is relevant to the page.
Teaching tips let users discover and initiate the related tour whenever they are ready for it.
Allow users to get on with a task right away without blocking them.
A teaching tip can be defined for any page (including request pages for reports) in Business Central, except the role centers, and dialogs.
After users dismiss a teaching tip and tour, they can choose or hover over the page title. This action will reopen the teaching tip, and the user can retake the tour, for example.
On a page that is opened from the checklist, the tour is considered an invited tour, and the page teaching tip has a Go back button that takes the user back to the checklist.

The following illustration shows a page teaching tip that explains what the page is about and can invite the user to take a tour. The teaching tip renders in the lower left corner.

A page in Business Central with a page teaching tip at the lower left corner.

The following illustration shows how choosing the page title will reopen the teaching tip so that the user can retake the tour.

Illustration of page with a teaching tip pointing to the page title.

How to write page teaching tips

There are different rules for teaching tips for lists versus cards and documents.

List page with teaching tip	Card page with teaching tip

AboutTitle: About sales invoices AboutText: Sales invoices appear in this list until they're finalized and posted. After an invoice is posted, find it again in the Posted Sales Invoices list.	AboutTitle: About sales invoice details AboutText: You can update and add to the sales invoice until you post it. If you leave the invoice without posting, you can return to it later from the list of ongoing invoices.
Answers the following questions: What can I do on this page in general? Is there a related entity I should know about? The title for a list page teaching tip will typically use the plural form, such as About sales invoices	Answers the following questions: What can I do on this page with this particular field or action? What is the desired outcome of the task in this page? The title for a card or document page teaching tip will typically be [entity name] + details, such as About sales invoice details

What you should know about tours

Tours are sequential teaching tips describing functionality while pointing to elements in the UI.
The tour guides the user around the page.
Tours can be initiated from the page teaching tip
During a tour, a page with input fields will be in read mode.
Tours show where to find something, what it is, what it means, what you can do with it, and what it affects.
A control teaching tip can point out a value that the user must check to know their next step.
- Example: The Status field on an invoice. When the status is open, the user can edit the invoice.
A control teaching tip can describe the relevant timing for when to use a field or action.
- Example: The Post action: When done editing, then post and send.

How to write teaching tips for controls

There are different rules for teaching tips for input fields and actions.

Teaching tip pointing to an input field	Teaching tip pointing to an action

AboutTitle: Who you are selling to AboutText: This can be an existing customer, or you can register a new from here. Customers can have special prices and discounts that are automatically used when you enter the sales lines.	Content example for the Post action: AboutTitle: When all is set, you post AboutText: After entering the sales lines and other information, you post the invoice to make it count. After posting, the sales invoice is moved to the Posted Sales Invoices list.
The teaching tip can point to a field that may or may not have data. A control teaching tip can explain an important value's meaning, such as what leaving the field blank does. Avoid stating the obvious and avoid action language that tells users to do something that isn't active during the tour. For example, don't say Enter the customer name here. Instead, explain what to be aware of when adding a customer.	With multiple similar actions,such as Post and Post & New, call out the simplest version only. Avoid action language that tells users to do something that isn't active during the tour. Don't say: Now post the invoice. Instead, explain what to be aware of when posting.

Teaching tips for FactBoxes

INTRODUCED IN: Business Central 2021 release wave 2

You can add teaching tips for FactBoxes just like pages by using the AboutTitle and AboutText properties is AL.

Adding teaching tips to FactBoxes

Teaching tips are supported on all page types that are supported in FactBoxes, including pages that display cues. Specifically, you can add teaching tips to following elements:

On the part control that contains the page or cue.
The page or cue that is included in the part control.
Controls, like fields, on the page or cue.

When adding teaching tips, consider the following limitations:

You can't add teaching tips to actions or control add-ins in FactBoxes.
For FactBox teaching tips to activate, the hosting page must have a page teaching tip. The page doesn't need any control teaching tips.

How FactBox teaching tips fit into tours

The teaching tips for FactBoxes become part of the tour on the hosting page. For more information, see Teaching tips flow.

Teaching tips for reports

You can add teaching tips for report request pages just like normal pages by using the AboutTitle and AboutText properties in AL.

Reports must be documented because they help users take data-driven decisions and are therefore key for users to run their business processes. With teaching tips, you can help explain logic that is relevant to the report therefore allowing users to get on with their reporting task right away without blocking them. After users dismiss a teaching tip, they can choose or hover over the report title in the request page. This action will reopen the teaching tip.

The following illustration shows a report request page teaching tip that explains what the report is about. The teaching tip renders in the lower left corner.

A report in Business Central with a request page teaching tip at the lower left corner.

Teaching tips flow

When designing teaching tips for a tour, it's important to understand the order in which teaching tips appear. The flow is as follows:

Content area of the main page
1. Page teaching tip
2. Control teaching tips
Action bar of the main page
FactBoxes
1. Part control teaching tip
2. Page teaching tip
3. Control teaching tips
System teaching tips. These teaching tips are for standard features that added are added by the platform and aren't controlled by AL.

Rich text guidelines for teaching tips

APPLIES TO: Business Central 2022 release wave 1 and later

2022 release wave 1 adds support for rich text formatting for teaching tips. In this section, we take a look at the rules and guidelines to follow when using rich text in teaching tips, such as bold, italic, or links.

Bold

Bolded text can call out the most important points, such as

Page names, such as Customer Card
Key features, such as Search
Field names, such as Customer
Keyboard shortcuts, such as Alt+Q

Best practices for use of bolded text

Use bolded text sparsely to avoid "shouting".
If a page name or key feature is title cased, it might be a candidate. However, consider if using bold is needed to help understanding the message.
Consider the difference between a page name such as the **Posted Sales Invoices** list (bolded and capitalized page name) as opposed to what the list contains such as the list of posted invoices (not capitalized and not bolded).
If the feature is already mentioned in the title, consider if it's necessary to highlight the word again in the body text. Bolding a word once in a tip is usually enough.

Italics

Italic text can be used to bring attention to key terms or field values, such as the following:

Key term, such as general ledger
Field value, such as Closed

Example of Tour Teaching Tip describing the field value Closed marked with italic

Links to open pages

Adding links to page teaching tips can be relevant in the following cases:

Links can be added to page teaching tips, to help users discover a key related page in Business Central, such as linking to the Item Templates page from a teaching tip on the Items list page.

Best practices for use of links

Use links sparsely and use only in page teaching tips. It may be confusing to send users elsewhere.
Don't use links in tour teaching tips, as it will disrupt the tour experience.

The following illustration shows a page teaching tip with a link to guide users to a related page in Business Central, such as the Posted Sales Invoices list, that users might be looking for in the Sales Invoices list.

Example of a Page Teaching Tip with a link to guide users to a related page object, such as the Posted Sales Invoices list, that users might be looking for

Common pitfalls

When you want to call out page names with bold, make sure only the caption is marked, such as **Sales Invoice** page or **Sales Invoices** list. In these examples, "page" and "list" don't have and shouldn't have rich text applied.
Don't apply multiple rich text styles to the same word. Apply one type of formatting only, bold, italic, or a link.

Tooltips and control teaching tips are complementary

There are different rules for tooltips and teaching tips.

Tooltip pointing at a field caption	Teaching tip pointing to a field

Guidance for tooltips: Every field and action has a tooltip. Answers the question What is this? Relevant for everything since every field/action has a definition.	Guidance for control teaching tips: Only the most important fields/actions have a teaching tip. Answers the question What can I do with this field or action? Isn't relevant for every field/action. Teaching tips guides users to fields/actions to be discovered and focus on.

For more information about tooltips, see Help users get unblocked.

Best practices for teaching tips and tours

Not all pages and reports in Business Central need teaching tips and tours. Use teaching tips where they provide value.
A teaching tip says what can be done (outcome), not how to do it (steps)
A teaching tip is short, and easily read. Usually just two or three short sentences.

Do

Use easy to understand titles that are relevant to the element being pointed to.
Be concise with the information you provide in a teaching tip. Short sentences or sentence fragments are best.
Keep the tour as short as possible with 1-4 steps.
Titles with a question are OK to use, but use them sparingly.
Use positive cases, don't tell what you can't do.
Follow Microsoft voice guidelines

Don't

Don't provide how-to (steps) or instructional guidance in teaching tips. That content lives on learn.microsoft.com or in your own documentation.
Don't use large, unformatted blocks of text in a teaching tip.
Don't put obvious tip text, or text that simply repeats what is already on the screen.
If you can't find anything to say, maybe reevaluate if this teaching tip is needed.