Dynamics 365 Business Central User assistance model
The Business Central user assistance model is based on the following principles:
Get started
Home pages give easy access to key tasks so users can easily get started with work every day. Embedded user assistance implemented as teaching tips help users understand new or unfamiliar pages, and checklists make it easy to get started in a new company.
Get unblocked
Embedded user assistance implemented as tooltips answers most immediate questions about what fields and actions do.
Learn more
The Help menu and Learn more links on tooltips and teaching tips provide context-sensitive access to Help articles with more information.
Apps, extensions, and customizations are expected to follow the same model by applying tooltips to controls on page objects, and by providing links to Help for their functionality. For more information about customizing and extending the user assistance, see Contribute to the Help and Configure the Help Experience.
In this article, we'll talk about the user assistance model itself and what it does.
Help users get started
The user assistance concept of Get Started is not just about getting started with Business Central on the first day. It's also about getting started all the other days, and about getting started with infrequent and unfamiliar tasks. Any new product can be baffling at first. For infrequent tasks, even after months of using the product, users can find it hard to remember where that report is, or how to fill in that form.
The default version of Business Central online includes in-product tours to introduce the first users of a new tenant to the general user interface and the most used pages. The in-product search makes it easy to find pages or reports - provided that you remember what they're called.
We strive to make Business Central easy to get started with in the browser and in the apps for desktop and mobile devices. Assistance in the shape of wizards is helpful for setup or filling in data for a complicated report, for example. Home pages that are designed for a particular role or job help users get started with their daily work – they can easily get to their most important tasks, and that means that Business Central helps them get their work done more efficiently. Similarly, in-product links to videos give new users a quick introduction to how the product works.
Onboarding checklist
APPLIES TO: Business Central 2021 release wave 1 (v18.0) and later
To help users set up Business Central on the first day, partners can add required steps to the checklist. The checklist is intended to help users fill in necessary information and help themselves get familiar with Business Central. For more information, see Get Users Started with the Checklist.
Teaching tips and tours
APPLIES TO: Business Central 2021 release wave 1 (v18.0) and later
2021 release wave 1 brought an interpretation of teaching tips that you can add to your Business Central solution. Use the teaching tips from the onboarding framework to introduce users to complex pages, and to build tours that help users understand the purpose of a complicated area, for example. Create the teaching tips in code by setting the AboutTitle and AboutText properties.
Note
Teaching tips supplement the tooltips that provide descriptions for all fields and actions.
There are different rules for tooltips and teaching tips.
| Tooltip pointing at a field caption | Teaching tip pointing to a field |
|---|---|
|
|
Guidance for tooltips:
|
Guidance for control teaching tips:
|
For more information, see Teaching tips and in-app tours for onboarding users.
Help pane
APPLIES TO: Business Central 2022 release wave 1 and later
When the user opens the Help pane, they see content and links to learn more based on where they are in the product. Once users discover the Help pane, they will be able to help themselves get unblocked, we hope.
The Help pane shows up to four types of links:
A link about the current page
At the top of the pane, a card repeats the current page's teaching tip, if one exists. If there is no teaching tip, then the card provides a single link to an article about the page. This link is based on the page-level configuration of context-sensitive Help.
If Business Central can't find the relevant link, we show the landing page on zcusa.951200.xyz. For example, if the page was part of an app that didn't add context-sensitive Help mapping to Business Central, the Learn link defaults to the landing page.
Links to related articles from Microsoft Docs
These links are related to the current page and will change if you move to another page. The links are limited to the zcusa.951200.xyz site. If there are more than three links, choose the Show more link to expand the card. Choose any link, and the related article will open in a new browser tab.
Links to content for apps on the current page
These links are based on any app that extends the page or defines the page. These links are based on the page-level configuration of context-sensitive Help.
Links to other resources
Three links are always available in the Help pane: Links to the Help & Support page inside Business Central, the Keyboard Shortcuts article, and the Business Central community. These links are always shown, and the list cannot be modified.
If the automatically generated links do not answer the user's question, then the user can use the Search field to search Microsoft's content, both documentation and e-learning material. Currently, search in the Business Central Help pane cannot access sites other than the zcusa.951200.xyz site, including Microsoft Learn.
Help users get unblocked
Even the best designed user interface can still be confusing to some. It can be difficult to predict what users will find confusing, and that is why the base application includes descriptions for all controls and actions that can be accessed when you choose the caption of the control or action. In combination with descriptive captions and instructional text, these tooltips, or callouts, constitute the larger part of our current implementation of embedded user assistance, which is an important principle in today's world of software design.
The tooltips help users unblock themselves by providing an answer to the most likely questions the users might have, such as "What data can I input here?" or "What is the data used for?". Keep tooltips in mind when you develop the user interface of your solution.
These descriptions are applied to controls on pages rather than table fields. Table fields can be read-only in one page and editable in another, so the tooltips describe the difference. In Business Central, this type of "What is this field?" content is embedded in the page objects, and resource files can be used for translated user interfaces. For more information, see Working with Translation Files.
Most tooltips end with an automatically generated link to learn more as described in the Help users learn more section; however, tooltips for actions do not have Learn more links:
Tip
Users can always use the Ctrl+F1 keyboard shortcut to access the learn more content that is configured for the currently-selected item in the user interface. In 2022 release wave 1 and later, Ctrl+F1 opens the Help pane with automatically generated links to related content from Microsoft and partners.
The tooltips in Business Central are conceptually similar to field descriptions in Dynamics 365 Finance and related apps, and teaching tips in the Universal Windows Platform's Fluent Design guidelines. The onboarding framework in 2021 release wave 1 added another interpretation of teaching tips that you can add to your Business Central solution. For more information, see Teaching tips and in-app tours for onboarding users.
Guidelines for tooltip text
The Microsoft user assistance model requires a tooltip for all controls of type Action and Field that exist on page objects. Follow these guidelines:
If the control is a field, begin with the verb Specifies.
If the control is an action, begin with a verb in the imperative form , such as Calculate or View.
Include the most valuable information that users need to perform the task(s) that the field or action supports.
For example, for the Post action, do not write Post the document. Write, for example, Update ledgers with the amounts and quantities on the document or journal lines.
Describe complex options in tooltips for option fields.
Use a colon to call out the option name and its description. See example 3 below.
Try to not exceed 200 characters including spaces.
This makes the tooltip easier to scan so the user can get unblocked quickly. However, the UI will render longer tooltip text if you want to provide more detailed user assistance.
Do not use line breaks in the tooltip text.
The tooltip cannot render formatting or line breaks.
Examples
The following table shows examples of effective tooltips.
| Control Name | Tooltip |
|---|---|
| Password field | Specifies your company's password to the service that converts bank data. The password that you enter in this field must be the same as on the service provider's sign-on page. (175 characters including spaces) |
| Entries action | View the history of transactions that have been posted for the customer. (72 characters including spaces) |
| Account Type field | Specifies the purpose of the account. Total: Used to total a series of balances on accounts from many different account groupings. To use Total, leave this field blank. Begin-Total: A marker for the beginning of a series of accounts to be totaled that ends with an End-Total account. End-Total: A total of a series of accounts that starts with the preceding Begin-Total account. The total is defined in the Totaling field. (522 characters including spaces) |
Help users learn more
The content that Microsoft publishes under the user assistance concept of Learn more is intended to answer those questions that the user interface (including the tooltips) cannot answer, such as where that page fits into the bigger workflow, or what comes next, or what would be the alternative.
Users can access this content either through the Learn more link in tooltips, by choosing the Help menu, or by using the Ctrl+F1 keyboard shortcut.
Links in the Help pane
APPLIES TO: Business Central 2022 release wave 1 and later
The Learn more links on tooltips and the Ctrl+F1 shortcut now open the Help pane. In most cases, the pane shows the following types of content:
A link about the current page
At the top of the pane, a card repeats the current page's teaching tip, if one exists. If there is no teaching tip, then the card provides a single link to an article about the page. This link is based on the page-level configuration of context-sensitive Help.
If Business Central can't find the relevant link, we show the landing page on zcusa.951200.xyz. For example, if the page was part of an app that didn't add context-sensitive Help mapping to Business Central, the Learn link defaults to the landing page.
Links to related articles from Microsoft Docs
These links are related to the current page and will change if you move to another page. The links are limited to the zcusa.951200.xyz site. If there are more than three links, choose the Show more link to expand the card. Choose any link, and the related article will open in a new browser tab.
Links to content for apps on the current page
These links are based on any app that extends the page or defines the page. These links are based on the page-level configuration of context-sensitive Help.
Links to other resources
Three links are always available in the Help pane: Links to the Help & Support page inside Business Central, the Keyboard Shortcuts article, and the Business Central community. These links are always shown, and the list cannot be modified.
The partner-provided links are based on the mechanism for adding links through app-level and page-level configuration. For more information, see Configure Context-Sensitive Help.
The following screenshot illustrates the Help pane when it is opened from the Purchase Invoice page.
In this case, the Purchase Invoice page has not been extended by any apps. If two apps had extended the page, their page-level and app-level configuration would be used to add links on a card after the Related articles from Microsoft Docs card.
The base version of Business Central uses content that is published to an online library, (zcusa.951200.xyz/dynamics365/business-central), so that it can also serve as onboarding material and as feature overviews that you can share with prospects. The content is written in Markdown, and our source files are available in a public GitHub repo that you can extend for your customers.
Note
Currently, Business Central does not require the Help for your own functionality to be created in a specific format. But we expect you to make it available on a website that the users of your functionality can access. For more information, see Configure Context-Sensitive Help.
For the base version of Business Central, free online learning is also available on Microsoft Learn. For more information, see the Business Central on Microsoft training.
Feedback and contributions
On the zcusa.951200.xyz website, each documentation article encourages you to provide feedback. We've changed the mechanism a couple of times based on, well, feedback. Currently, we ask you to choose the Feedback action below the article's title. You can give the article a rating, and write a comment if you want to. The feedback goes straight to the article's author and the team that owns the docs.
We welcome your contributions, both as pull requests with suggestions or corrections to the content, and as GitHub Issues with bugs or questions. However, we can only accept feedback and contributions to the content in the dynamics365smb-docs and dynamics365smb-devitpro-pb repos. Also, we cannot address issues or questions about the product.
Important
If you have feedback about translations, you can report a GitHub issue in the dynamics365smb-docs repo.
For more information, see Contribute to the Help.
Working in Markdown
If you fork one of our repos, you will be authoring in Markdown. We recommend that you learn the basics by referring to the Learn Markdown reference section in the Learn Contributor Guide.
The Learn Authoring Pack for VS Code can aid with Markdown authoring and validation in Visual Studio Code. However, you can also use other text editors to edit Markdown.
For other tips and tricks, see Contribute to the Help and the blog post Collaborate on content for Business Central.
Translate the Help
If you want to deliver a localization app, or if you want to deliver your functionality in more than one country/region, you will want to translate the Help as well as the product. We suggest that you take a look at the Microsoft Dynamics 365 Translation Service, which is available as preview in Microsoft Dynamics Life Cycle Services. For more information, see Translate documentation files.
The user interface text, including the tooltips, is translated as part of the application. For more information, see Working with Translation Files.
Style
At Microsoft, we are in process of simplifying and unifying our style guides. To get to know the Microsoft style, use the Microsoft Writing Style Guide as a good starting point. The Business Central follows most of the guidelines in the Microsoft Writing Style Guide with exceptions for industry terminology and other product-specific issues.
Get notified about changes through an RSS feed
To subscribe to a Really Simple Syndication (RSS) feed of all updates that are to the content on zcusa.951200.xyz across the developer and administration content for Business Central, use the following link:
Note
The RSS feed returns a list of the 100 articles most recently updated. The list is sorted by date, but it can take up to a week before the most recently updated articles make it to the list.
Related information
Configure the help experience
Adding help links from pages, reports, and XMLports
ToolTip property
InstructionalText property
Development of a localization solution
Translate documentation files
Resources for help and support
Blog post: Extending and customizing the Help
Blog post: Collaborate on content for Business Central
Docs contributor guide
Docs Authoring Pack for Visual Studio Code
Microsoft Cloud Style Guide (requires login)
Microsoft Writing Style Guide
Onboarding experiences in Business Central
Teaching tips and in-app tours for onboarding users