Authoring Guide for Dynamics 365 Business Central

If you are contributing to the Business Central Help, or if you are customizing and extending the Microsoft content for your own solution, you will probably want to use the same tools, processes, and style guide that Microsoft uses.

Resources

Write for accessibility

At Microsoft, we write for accessibility, which also means that the same content applies to interactions with the software across devices, regardless of input method, for example. For more information, see Describing interactions with UI in the Microsoft Writing Style Guide.

The accessibility requirements also impacts metadata for illustrations, such as the following:

:::image type="content" source="media/illustration.png" alt-text="Text used by screen readers.":::

Most of Microsoft's articles use a different MarkDown formatting for illustrations, such as the following:

![Lightbulb that opens the Tell Me feature.](media/ui-search/search_small.png "Tell me what you want to do")

Both formats are valid MarkDown, and both formats are supported by DocFx.exe. For more information, see Images in the Docs Contributor Guide.

Authoring in MarkDown

The Business Central content is styled using a MarkDown syntax as described below. Extended guidance is available in the MarkDown Reference section in the Docs Contributor Guide.

Headings

Use # for headings. For more information, see Headings in the Docs Contributor Guide.

In the source files for the Business Central content, which publishes as English (US) on the Docs.microsoft.com site, the title of an article is expected to use Title Case (capitalize each word, except prepositions) whereas subsequent headings use Sentence case (capitalize the first word, only). The Microsoft Writing Style Guide recommends a different approach.

Metadata

The content on the Docs.microsoft.com site includes metadata that is used by the site and feeds our internal telemetry dashboards. The metadata is required for Microsoft's content but not necessarily for content that extends or customizes Microsoft's content.

However, some metadata is recommended as a best practice as outlined in the following table.

Metadata tag Description
title Used by search engines. Recommended length of 60-70 characters, including spaces. We recommend that the title metadata is the same as the first heading in the article.
description Used by search engines. Recommended length of 100-160 characters, including spaces.
author GitHub account of the main contributor to the article.
ROBOTS Please apply this tag if you customize one of Microsoft's articles and deploy that to your website. By applying the metadata ROBOTS: NOINDEX, NOFOLLOW, you help make sure that search engines will find the original article rather than your customized version. Users of your Help will still be able to find the customized article through context-sensitive Help links and other links.

Bulleted lists

Use - or * to create bullets as shown in the following example:

The following options are available:

- first option
- second option
- third option

Tip

It doesn't matter if you use - or *, but the current version of the Docs Authoring Pack requires each article to use one or the other and not mix them up.

As a best practice, the MarkDown validation in the current version of the Docs Authoring Pack recommends a blank line between options in a bulleted list for better readability in MarkDown.

Ordered lists

Use numbers for ordered lists. Do not add spaces between the lines.

1. Choose the ![Lightbulb that opens the Tell Me feature.](media/ui-search/search_small.png "Tell me what you want to do") icon, enter **Payment Journal**, and then choose the related link.
2. In the **Payment Journal** window, on the first journal line, enter the relevant information about the payment entry.
3. To apply a single vendor ledger entry:
4. In the **Applies-to Doc. No.** field, choose the field to open the **Apply Vendor Entries** window.

Bold and italics syntax

Use **bold** and *italics*

Tables

For tables in the body, use the markdown syntax. The Docs Authoring Pack for Visual Studio Code has a shortcut for adding a table, and you can also use Tables Generator.

| To   | See                       |
|------|---------------------------|
|<text>|<link>|
| | |
| | |

MarkDown syntax for nested tables is limited, so we recommend using HTML-syntax for nested tables in ordered and unordered lists use HTML-syntax.

Placeholders

Rather than repeating text in two or more articles, use includes. For more information, see Included Markdown files.

For Business Central, we use includes for boilerplate text, for content that is repeated in more than one article, and for the product name. That way, we can make changes in just one location - and so can you.

Tip

In the dynamics365smb-docs repo, the includes are in the business-central\includes subfolder.

In December 2020, the two placeholders for the product name, prodshort.md and prodlong.md, were renamed to prod_short.md and prod_long.md. The change solved a problem internally at Microsoft, because we have a tool that helps identify spelling error, and that tool generated warnings for prodshort.md and prodlong.md.

Comment syntax

Useful for sections that are not ready and will not pass build checks.

<!-- Comments -->

Examples:

<!-- [Managing Payables](payables-manage-payables.md)-->
<!-- This is a paragraph that spans more lines and I can just put the comment tag
at the beginning and end of it -->

Ordinary link to a different topic in the same folder

These links have the format [link text](filename.md).

Example: [Managing Payables](payables-manage-payables.md)

These links have the format [link text](subfolder/filename.md).

For example, you want to link to payables-manage-payables.md from ui-work-general-journals.md, where the folder structure is as follows:

  • articles
    • ui-work-general-journals.md
  • ManagePayables
    • payables-manage-payables.md

Here is the link: [Manage Payables](ManagePayables/payables-manage-payables.md)

These links have the format [link text](../folder/filename.md).

For example, you want to link to payables-manage-payables.md from receivables-manage-receivables.md, where the folder structure is as follows:

  • articles
    • ManageReceivables
      • receivables-manage-receivables.md
      • ui-work-general-journals.md
      • ManagePayables
        • payables-manage-payables.md

Here is the link: [Manage Payables](../ManagePayables/payables-manage-payables.md)

Link to a place in the same article

From within an article, you can create a link to a specific heading in the same article. You can create the link like other links except with the following format:

[link text](#target-heading)

target-heading is the text of the heading that you want to link to, except it is all lowercase and spaces between words are replaced with hyphens. For example, here is the link: [How Autoscaling Works](#how-autoscaling-works)

To the heading: ## How Autoscaling Works

Link to a place in a different article

From an article, you can create a link to a specific heading in another article. You can create the link like other links except with the following format:

[link text](targetarticlename#target-heading)

targetarticlename is the file name of the article, including the .md file type. target-heading is the text of the heading that you want to link to, except it is all lowercase and spaces between words are replaced with hyphens.

For example, to link to the heading "How autoscaling works" in the article Autoscaling.md, add the following code: [How autoscaling works](Autoscaling.md#how-autoscaling-works)

If your website supports two or more locales, you can use DocFx to generate HTML files for the relevant languages. However, you may experience problems with links to anchors, also known as bookmarks.

For example, if your content has a link from article1.md to a specific section in article2.md, that link would be formatted like this: [My translated subheading](article2.md#my-translated-subheading). Then, when you run DocFx to generate HTML files in Danish, DocFx will convert that link to [Min oversatte overskrift](article2.md#min-oversatte-overskrift). That is not a problem because the link will work in both English and Danish.

But if you then want to use that link elsewhere, the link only works for one of the languages because the anchor changed its name in the Danish translation. If you link to that subheading in article2 from your marketing site or support site, or if you use it as the value of the ContextSensitiveHelpPage property, then it only works in English.

To work around this problem, we recommend that you create explicit anchors by tagging your subheading to give it a fixed anchor. The following example illustrates how that would look in MarkDown:

### <a name="subheading"></a>My translated subheading

You would then be able to use the same link across all locales: [My translated subheading](article2.md#subheading), which would render in HTML as myurl.com/docs/article2#subheading across all languages.

For more information, see Using hashtag in cross reference in the GitHub documentation.

Note

Adding fixed anchors is only relevant if you want to generate a link to a subheading that works consistently across languages.

Line breaks (soft return)

In the editor, add two blank spaces at the end of the sentence and hit return. This is used in the See Also list. (See Also must be heading 2.)

Continue steps after a non-step para

Enter four spaces in front of the non-step para. Otherwise, the non-step para will restart the step sequence.

TOC

The TOC structure of the TOC.md file is as follows:

#[Overview](overview.md)
 ##[Topic 1](topic-1.md)
 ##[Topic 2](topic-2.md)
 ##[Topic 3](topic-3.md)
 ##[Topic 4](topic-4.md)

Standard phrases

All fields in Business Central have tooltips; therefore, do not document fields in Help. To refer readers to the tooltips, use this standard phrase where relevant:

"Choose a field to read a short description of the field or link to more information."

For more information, see Business Central User Assistance Model.

Recycle content

Rather than copy-pasting content that you want to surface in two or more places, use includes. For more information, see Included Markdown files in the Docs Contributor Guide.

Topic titles

  • Use imperative verb form for step-based topics ("Pay vendors").
  • Use gerund verb form for conceptual, non-step topics. ("Paying Vendors")
  • Use nouns for highest-level topics. ("Sales")

File naming

In this section, we describe best practices for file names of MarkDown files that will publish to a website. The guidelines make the files easier to work with and better for search engines to index.

Rules

  • No spaces or punctuation characters. Use hyphens to separate the words in the file name.

  • Use all lowercase letters

  • No more than 80 characters - this is a publishing system limit

  • Use action verbs that are specific such as develop, buy, build, troubleshoot. No -ing words.

  • No small words - don't include a, and, the, in, or, etc.

  • All files must be in markdown and use the .md file extension.

    New FAQ files must use YAML format. For an example, see the https://github.com/MicrosoftDocs/dynamics365smb-docs/blob/live/business-central/faq-copy-paste.yml file.

Examples of file names

Topic title Naming
Select a Company ui-how-select-company.md
Enter Criteria in Filters ui-enter-criteria-filters.md
Troubleshooting: Record Locked by Another User ui-troubleshoot-record-locked-another-user.md
Changing Basic Settings ui-change-basic-settings.md
Sales sales-manage-sales.md
Set Up Currencies finance-setup-currencies.md
Set Up Purchasers purchases-how-setup-purchasers.md
Understanding Session Timeouts admin-understand-session-timeouts.md
Manage Data Encryption admin-manage-data-encryption.md

Country-specific content

To simplify content localization and translation, country-specific articles live in country-specific folders. The TOC entries live under the "Local Functionality" parent node.

User interface text

If you're a technical writer, then you're likely to either write or edit user interface text, such as captions, warnings and error messages, tooltips, and teaching tips. In this section, we describe our internal guidance, but you can choose differently.

Tooltips

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 of tooltips

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)

Errors, warnings, and other messages

Messages that users see when they work in Business Central, some as confirmations, others as warnings, for example, are defined in code. In this section, we describe key things to keep in mind when writing or editing this type of user interface text.

  • Be brief but descriptive with clear call to action.

    Especially true for errors and warnings that must help the user unblock themselves.

  • Write to be understood worldwide.

    • Write content that's easy to read and translate.
    • Avoid long, complex sentences. Break them up into shorter sentences that are easier to read and comprehend.
    • Use lists and tables instead of complicated sentences and paragraphs.
    • Use standard English grammar. In particular, avoid incomplete sentences.
    • Include words that native English speakers often omit, such as that and the.
  • Only use placeholders for variables and field values where the result depends on context.

    Write out all static captions, where the value is always known.

  • All placeholders complicate translation, also valid ones, even when they are preceded by code comments.

    A typical challenge is to determine the gender of the noun that a placeholder represents. This is problematic for target languages such as French, German, and Russian.

    Use Instead of
    The document has been posted. The %1 has been posted. (Translators cannot determine the gender.)
    The Unit Cost field is updated. The %1 field is updated. (Where %1 always represents "Unit Cost".)
    Document %1 contains invalid characters. (Where %1 represents a given document ID.)
    Option %1 is not supported. (Where %1 represents one of more options.)
  • Do not place quotation marks around placeholders.

    However, if the placeholder represents free-text user input that is hard to distinguish, such as a payment comment on a bank transaction. The quotation marks then helps to distinguish the user input from other parts of the message.

    Example: The payment line with transaction text '%1' is not applied., where %1 = Hi - here is my payment of invoice 1223344.

Teaching tips

APPLIES TO: Business Central 2021 release wave 1 and later

With 2021 release wave 1 comes a new intepretation 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.

See also

Business Central User Assistance Model
Extend, Customize, and Collaborate on the Help
Configuring the Help Experience
Docs Contributor Guide
Docs Authoring Pack for Visual Studio Code
Getting started with writing and formatting on GitHub
Visual Studio Code
Atom
DocFx
Blog post: Extending and customizing the Help
Blog post: Collaborate on content for Business Central