This style guide uses a cascading approach. In the first instance, use the guidance described here, if you can't find what you're looking for or need more information, use the Microsoft style guide resolve any issues. If you're looking for specific guidance on a specific word, use the Merriam Webster dictionary.

This guide is maintained by Caroline Domenech, if you have questions about anything you see here or would like to provide feedback, contact caroline.domenech@moodys.com

Accessibility and inclusivity

Moody's Analytics KYC wants to write for everyone, everywhere. This means supporting the inclusion of multiple perspectives from diverse audiences. We want to avoid assuming our customers are one gender, race, or class.

One way to support inclusivity is by making sure our language doesn't show unintentional bias.

Consider using the following alternatives to common terms as a step toward improving inclusivity. Some exceptions may have to be made, such as for industry standard terms like the FATF blacklist.

Anti-racist language:

Alternatives to the white is positive and black is negative comparisons.

• Instead of whitelist, use allow list and instead of blacklist, use block list.
• Permitted/not permitted

Alternatives to master/slave:

• Parent/child or dependent
• Primary/secondary
• Primary/replica
• Leader/follower

Alternatives to ableist language:

• Active/deactivated or inactive instead of enable/disable
• Typical/atypical instead of normal/abnormal

Ungendered language:

• Chair or Chairperson instead of Chairman/woman
• When the subject or person is unknown, use the singular they or you
• Person/individual instead of man/woman

Accessibility

Avoid using directional words such as above/below, top/bottom, or left/right. These words can be confusing to those using screen readers. Additionally, these terms can also create challenges for localization, for example into right to left languages. Instead, use words that indicate sequence, such as preceding or following.

Alternatively, orient the user by referring to on-screen signposting. Direct end-users to orient themselves by sign-posting with specific buttons, columns or other UI elements instead.

Use the WCAG guidance to see more details around specific issues related to web accessibility.

Grammar and mechanics

Abbreviations

Use periods in these common abbreviations: Mr., Mrs., Ms., Prof., or Dr.

Avoid Latin abbreviations as they can be misinterpreted and cause problems for screen readers and localization.

• Use 'that is' instead of i.e.
• Use 'for example' instead of e.g.
• Use 'and so on' instead of etc., or consider removing it, since it can be vague.

Acronyms

Unless it's an industry standard term, such as URL or API, spell out the full term on initial use before referring to it as an acronym or an initialism.

Active voice

Choose active voice over passive voice, as it is more direct, engaging, and easier to read. In active voice it is clear that who or what is doing the action.

Ampersand (&)

Addresses

Use open punctuation in addresses. In other words, leave out nonessential punctation.

For example:

Moody's Analytics KYC 1 Canada Square London E14 5FA

If it's not possible to show the address in this format, use commas to separate each line and a period at the end if it is the end of a sentence.

Example: Moody's Analytics KYC, 1 Canada Square, London, E14 5FA.

Apostrophes and contractions

Contractions can make writing feel more conversational and friendly, however, they shouldn't be used in a way that makes the content unprofessional or overly familiar.

Bold and underlining

If necessary, use bold sparingly to emphasize text. If you're not sure, then don't use bold. Don't underline copy to highlight it unless it's a URL or email address.

Button labels

Button labels are the most important part of the button because it tells the user what will happen when the user interacts with it. Button labels need to contain actions, for this reason, button labels should start with a verb and be no more than 2-4 words. Additionally, the labels should be logical to the main content, for example, if you're advising a user to import content in a modal, the button label should include language around importing.

Use sentence case.

For example:

• Continue upload/Cancel
• Save/Go back
• Add new check

Capitalization

Use sentence case, except when using a proper noun. A proper noun refers to a specific instance of a noun, such as company names, job titles, product names, or peoples' names. If you're unsure whether to capitalize something, don't capitalize it.

Currency

Use two decimal places and put the currency symbol before the amount: $450.00. For currencies that share a currency symbol, for example CAD and USD, combine the use of the symbol with the ISO currency code in the following format: CAD $110.00.

If you need to show a fraction or decimal place, use a 0 and a period: £0.95.

Use commas, not spaces or periods, to indicate thousands: £3,000.

In the UI, where space may be limited, use the symbol to indicate the currency, but include the currency name in a tool tip or hover hint.

Dates and time

Displaying dates

Capitalize the names of months and days and their abbreviations. Use 3 letter abbreviations when needed. Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec
Mon, Tue, Wed, Thu, Fri, Sat, Sun

Don't use punctuation in dates.

• Today
• Yesterday
• Mon 7 Jun 2022
• 4 Apr 2023

Time

Use AM and PM preceded by a space. Use capital letters for AM and PM.

• 9:23 AM
• 4:23 PM

Displaying time and date together

• Today at 9:23 PM
• Yesterday at 9:23 PM
• Monday 30 September 2022 at 9:23 PM
• Mon 7 Sep 2023 at 9:23 PM
• 30 Sep 2024 at 9:23 PM

Ellipses

Use ellipses in the UI when there are space constraints, but make sure the user's action or task is still obvious.

Use the ellipsis character rather than three consecutive periods.

For example: Import your policy to…

Error messages

Error messages should be friendly, helpful and concise. Don't use the words please or sorry and avoid flowery language. An error message should contain a minimum of 3 parts:

1. What happened should be written in plain English, clearly stating the problem. This can be the title or header of the error message. For example: The policy failed to upload.

2. The cause should be written in plain English, without jargon. This briefly summarizes what went wrong. For example: Your policy failed to upload because another upload is already in progress

3. Include instructions on how to fix the error or the next step a user needs to take to resolve the error. For example: Wait for the previous policy to finish uploading or cancel it and upload the required policy.

Exclamation points

Avoid using excalamtion points in the UI.

File extensions

When referring generally to a file extension type, use all uppercase without a period.

Add a lowercase 's' to make an extension plural, for example: GIFs, PDFs, HTMLs, JPGs.

When referring to a specific file, the filename should be lowercase, for example: graphing.gif, ma_benefits.pdf, twitter-profile.jpg, ilovedoughnuts.html.

Jargon and slang

Jargon is specific words used by a profession or group that can be hard for other people to understand. As not all of our customers are familiar with these specialist terms, don't use jargon.

Avoid slang, as such informal language doesn't translate across regions and cultures. In some cases, it may even be considered offensive.

Job titles

Job titles are treated as proper nouns and therefore capitalized.

For example: Prime Minister, not Prime minister and Chief Executive Officer, not Chief executive officer.

Links

Use meaningful link text that refers to the title of the page or describe the nature of the linked document or webpage instead of using generic link text like click here.

Use phrases like Go to or Open to describe link behavior. Example: Go to the CIFAS portal.

Lists and bullets

For lists where the order is unimportant, use standard bullets and a serial comma.

If nested bullets are needed, make sure the bullets alternate in list type.

• In an ordered list, use a different numbering system in the secondary level than in the primary level.

Ordered lists should only be used for procedures and sequential events or when the order of items is relevant. For example:

1. Select Create new profile.
2. Enter the individual's details.
3. Select Finish.

Moody's Analytics - use of the name

Moody's Analytics should always be spelled out in full.

Example: Moody's Analytics provides award-winning solutions to financial risk practitioners globally. Our data, models, software, and expertise empower our customers to better measure, monitor, and manage risk. Moody's Analytics offers a powerful combination ALM solution for banks that integrates enterprise ALM, FTP, business management, and regulatory compliance.

Names

The names of people with initials should have a space between the initials with no periods. For example: Paul D Smith or P D Smith.

Organizations' names, such as WH Smith, SBC Warburg, IG Metall, have no spaces or periods.

Numbers

Spell out whole numbers from zero through nine. Use numerals for 10 or greater.

This applies to all use cases, except when it comes to millions and billions, which should be spelled out, for example 10 million.

Phrasal verbs vs nouns

Phrasal verbs are verbs that are made up of more than one word, for example, log on or set up. These can get mixed up with nouns. If it is a noun, these words can be combined, however, if it is a verb, the words are kept separate.

Example:
Noun phrase: Enter your login to access the platform.
Verb phrase: Log in to the platform.

Please and sorry

Avoid adding the words please and sorry; use these words sparingly. Simple, direct language and commands get the message across faster.

Positive language

Write positively.

Product names

Product names should be treated as proper nouns unless otherwise stated. Some brands may contradict this ruling and should be written as per their existing brand rules.

For example: Kompany refers to their cloud-based platform as KYC workspace whereas Passfort describes their customer lifecycle management solution as Passfort Lifecycle. Both styles should be respected.

Pronouns

This/That/These/It This/That/These/It are pronouns. They refer to another noun, but they can introduce ambiguity if it's not clear which noun they're referring to, so use them wisely to make the copy as clear as possible.

You/We/I/My These are personal pronouns.

Use the pronoun you to talk to and engage the reader directly. Using you as a pronoun helps avoid the passive voice and makes the tone more human.

Using the pronoun we for Moody's Analytics KYC, the business unit, or Moody's more broadly is fine, it can humanize the company, but it might also create confusion about who is included in that we, so write around it where possible.

My and I should be avoided where possible.

Punctuation

Brackets

Avoid brackets in copy. If you have to put something in brackets, ask why. Should it be there at all?

If the text in brackets is important to the meaning of the sentence, use commas instead or break into multiple sentences.

Commas

Use serial commas. Serial, or Oxford, commas, are commas used before the last item in a list.

Dashes, hyphens, and slashes

Don't add spaces before or after these punctuation marks.

Use hyphens for multi-part words such as up-to-date or read-only.

Periods

End complete sentences with periods in content writing.

In UI and API documentation, if there are one or more lines of text, use periods. A single line doesn't need a period.

Quotation marks

In American English, all punctuation sits inside the quotation marks.

Ranges

Use the word 'to' to connect ranges.

• Monday 30 September 2018 to Monday 30 September 2019
• Mon 30 Sep 2021 to Mon 30 Sep 2022
• Medium risk: 100 to 500

Spelling

Use American English.

American spelling	British spelling
authorize	authorise
gray	grey
center	centre
liter	litre
analyze	analyse
license	licence
catalog or catalogue	catalogue
program	programme or program
color	colour
enrol	enroll
canceled	cancelled
inquire	enquire

In American English, practice is a noun and a verb. In British English, the verb is practise.

Watch out for license and defense too, which are spelled with an 's' for both the noun and verb in American English. British English uses a c for the nouns.

Refer to www.merriam-webster.com for more information on language usage, especially American spelling.

Tense

Write in the present tense.

Web and email addresses

Email addresses and URLs should appear in lower case, underlined, and linked, for example info@moodys.com and www.moodys.com.

Don't include http: or https: at the beginning, but do include the www., and end with a period if the web address or email appears at the end of a sentence.

Help documentation

Audience

Write for the broadest possible audience. When you write, keep the UX user personas in mind, in order to determine the organization of the information. Assume your audience has multiple skill levels, both technically and domain-wise.

Focus on supporting end-users to self-serve while using the UI but consider, also, the role that internal stakeholders play. Internal stakeholders may require some support in the form of notes.

Formatting

Use the <guilabel> and <guibutton> styles when referring to UI elements. The <guibutton> style should be used to refer to UI elements that the user interacting with directly. Example: Enter the customer's name in the First name field.

Use the <guilabel> element when referring to a UI element that a user is not explicitly interacting with but you are referring to the UI for orientation or confirmation.

Emphasis

Use italics and bold sparingly, overuse can make it difficult to know which parts of the text are important and they can cause screen readers difficulties.

Headings

Use one H1 per page. Follow the correct order of heading levels: H1, H2, and then H3. Don't follow an H1 with an H3.

Avoid empty headings or headings with no related content.

Use the infinitive form of the verb in titles. This is because using a gerund, or -ing form, can be inconsistently translated as well as increasing the cost and character count in localized content.

Interactions with the UI

Use the word select when you're instructing the end user to pick something from a number of choices, such as from a list or dropdown menu.

Example: Select a configuration option.

Use the words choose or add when you're instructing the end use to make a choice that's more open-ended, such as a custom field or free text field.

Example: Choose a decision reason to apply to the application.

Unless there are multiple UI elements with the same label, avoid adding the word button.

Lists

Introduce lists with a lead-in and end the line with a colon. Items in a procedure and numbered lists should be full sentences and end in a period.

• Use a bulleted list for things that have something in common but don't need to appear in a particular order.

1. Use the numbered lists for items, where the number of items is significant or priority is important. Use the numbered lists with icons for procedures and instructions.

How to topics

According to the Diataxis framework, "How-to guides are directions that take the reader through the steps required to solve a real-world problem. How-to guides are goal-oriented."

When creating a new how to topic, use the template built in Paligo.

Headings

Use-task oriented titles that begin with a verb and follow all other heading guidance.

Lead-ins or intros

A good lead-in should include context for the feature and include the following information.

• Link to relevant reference topic
• Description of the feature
• The benefit the feature brings to the user
• Prerequisites or caveats

Links

Include links to explanation topics at the beginning of the how-to topic.

Notes, caveats and cautions

Notes, caveats and cautions should always appear immediately following the relevant content. The exception to this is when they apply globally, in which case they should be a part of the lead-in.

Prerequisites

These can be required permissions, links to get started topics or any other tasks that need to be completed before starting this one. Include prerequisites in as a part of your lead-in.

In Paligo, use a <sidebar> element to create the Prerequisites and assign <accordion> as the role.

Procedures

Avoid writing any long procedures. A good rule of thumb to follow is that procedures should be no more than 7 steps. Consider breaking larger procedures into subtasks.

Sections

Avoid adding more than three related tasks to any one how-to topic.

Tutorial topics

• Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. Tutorials are learning-oriented.
  
• Diátaxis framework

When creating a new tutorial topic, use the template built in Paligo.

Headings

Preface tutorial topic titles with "Tutorial:" unless the tutorial will sit in a separate Tutorials section on the help site. Start the title with an infinitive.

Example: Tutorial: Create a risk model for an individual profile

Introduction

The introduction should tell the user what they will achieve by following the tutorial. Include details of the specific example the tutorial will follow.

Example:In this tutorial, we will create a sample risk model for product applications by individuals. Applications are assigned a risk level as follows (etc.)

Prerequisites

Include prerequisites as part of the introduction to the tutorial. Prerequisites could include:

• Required permissions
• Links to preceding tutorials
• Any tasks that need to be completed before starting the tutorial

In Paligo, use a <sidebar> element to create the Prerequisites and assign <accordion> as the role.

Procedures

Tutorial steps should be concrete, providing only the minimum necessary information needed to complete the step. An explanation of all the available options should be left for the how to guide. Minimize the number of steps involved in the procedure; consider breaking larger procedures into subtasks or simplifying the tutorial example.

Links

Include links to related information or next steps in a section at the end of the tutorial. This section can be titled <Related information> or explicitly <Next steps>.

Screenshots

• Use PNG file format.
• Must include alt text.
• Should be placed inside the step the screenshot is supporting.
• Use a product called "Forexo Basic Account" for individuals and a product called "Forexo Pro Account" for companies.
• Use the distinct and nicely named tasks/products. Avoid using more than necessary so the reader is not distracted.
• Use the demo names for individuals, companies, fake credit cards, and other data. Don't use real names or data.
• Sign in with an account that looks like one a user might see. Avoid using an admin account because it may have employee-only features.
• Avoid using more than two callouts on a single screenshot.
• Where possible, show an image of the modal with as much completed detail as possible.
  • Example: Include a cursor in the screenshot, especially where the text says “Select X to Y.”
• For the screenshot borders, use #B0BEC5 (gray) with a 3pt width.
  • Crop to square up edges in modals with rounded corners.
• For callouts:
  • #FF8522 (orange) in the first instance, if there is a contrast/clashing issue, use #A1023D (burgundy)
  • Use a square call out with rounded corners (border-radius: 8px), no shadow
  • For steps, use Bliss Pro font, #FF8522 (orange) fill, no additional border, no shadow

Tables

Large tables should be added to the Reference section with a lead-in and links back to the relevant sections.

Voice and tone

What are voice and tone?

Voice and tone are the way we communicate Moody's Analytics KYC personality to our audiences. We aim to be friendly, direct, and knowledgeable. Avoid jargon, superlatives, and long sentences, our copy is easy to read.

Voice

The KYC business unit's voice can be encapsulated by three adjectives. We use these adjectives as a guide when creating content, regardless of whether we're writing marketing collateral, UI copy or quick reference guides.

Clear Plainspoken, concise

• Write as clearly as possible, without introducing ambiguity or relying on jargon
• Simplify anything complex and try to improve readability
• Write at a level that appeals to your audience that has varied skill sets and capabilities

Genuine Trustworthy, informed

• Offer customers and audiences the most up-to-date information, avoiding stale content and concepts
• We don't need to use hyperbole or overpromise in our messages • We relate to our audiences' interests and challenges

Dynamic Innovative, solutions-oriented, optimistic

• Write positively
• Provide valuable, practical advice for your audience
• Continue to evolve our language and content based on user feedback

Tone

Tone conveys mood. It's the way we express the personality defined by our voice. Our tone should be adapted to the context of the message. For example, for error messages our tone should be helpful and knowledgeable; for blogs it can be knowledgeable yet conversational.

This table shows examples of voice and tone in context. Moody's Analytics KYC voice and tone should be balanced, bearing in mind the business unit's place within the wider Moody's brand. For example:

Too formal	Too casual	Just right
Select the Remove button in order to update the Verification list.	Hit the Remove button to get rid of the person from the Verification list.	Select Remove to update the Verification list.
Ensure that any previous imports have been canceled before uploading a new one.	Don't upload a new policy until you have canceled the old ones.	Make sure that you have canceled ongoing imports before trying to upload a new policy.
The Configure and send request modal allows you to view and deselect the forms that you intend to send to the customer.	Look at forms you're sending to the customer in the Configure and send request modal.	The Configure and send request modal shows you which forms you are sending to the customer.