COSMO-specific Styles

The content on the https://docs.cosmoconsult.com site generally follows this style guide. The content for the different manuals varies in certain ways, partly with product-specific terminology.

Note

Our documentation projects are written in English (US spelling). For further information, see File Naming.

General

  • We don't need to include trademarks such as Microsoft Dynamics 365 Business Central®. Just write: Microsoft Dynamics 365 Business Central.

  • Don't abbreviate any of the Microsoft Dynamics 365 names or turn them into acronyms. For example, write Microsoft Dynamics 365 Business Central. You can omit Microsoft if the word Microsoft has already been used in text earlier in the communication — like in an earlier reference to a product name.

  • Define acronyms - Define this in words within the content, followed by the acronym in parentheses before using it, for example: It offers a wide range of Product Data Management (PDM) features.

  • Exclamation points (!) should not be used.

  • Do not use ambiguous words, for example as vs. because. Because is clearer for translation.

  • Do not use please unless you are describing a situation that inconveniences the user in an unusual way or are asking the user to wait.

  • You vs. User

    • Change user / the user / users / he / she etc. to you if possible, or rewrite sentences to exclude user or you.

  • Checkboxes that are now toggles

    • Use the following descriptions:
      • Turn on (or off) the xxx toggle.
      • If the xx toggle is turned on in the xx page and so on.
      • If the xx toggle is turned off on the xx page and so on.
Note

Don't forget to keep in mind the basic principles of the COSMO Communication Guideline.
For more information on Microsoft writing style and terminology, see the Microsoft Writing Style Guide.

Formatting

Bolding and italics are used to emphasize certain UI elements and input to help users locate and interpret information.

Use bold to emphasize product names (for example, COSMO Data Integration Framework) and UI elements such as Fields, Actions and Objects.

Note

Add the word action, field, or button after the UI element.

Example
Choose the Post action to post the order.

Use italic to emphasize values for frontend usage.

Example

In the Customer Name field, enter 10000.
In the Quantity field, type 10.

For backend usage, that is, technical content, wrap it with one backtick quote (`) for highlighting.

Example

RoleID = CCS <Solution Prefix> <Role Type> (e.g. CCS DMS ALL, CCS DIS MIN, CCS DIS ADMIN)

Standard Phrases

All fields and actions in Business Central can have tooltips. Therefore, do not document fields in Help, but try to use the tooltips to answer most immediate questions about what fields and actions do.

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 on how to write tooltips, see Guidelines for tooltip text.

Writing Tips

More information on how to make content that’s easy to read, see Microsoft Writing Tips.