Grammar and formatting

Discover our key grammar principles.

Abbreviations

Use abbreviations that are familiar to users, don’t invent new ones. It can be useful to spell out a less common acronym the first time it’s used, and then use uppercase letters.

Avoid Latin abbreviations, the English sentence will be clearer to most users.

Use 'For example' instead of 'e.g.'

In full sentences, write words entirely. Avoid short forms unless you have space constraints, in a table for instance.

Including/Excluding

  • Incl. tax

  • Excl. tax

Active and passive voice

Use the active voice rather than the passive voice as much as possible

The active voice says ’who did what’ instead of ‘what was done’. It’s more direct and it’s easier to understand. It'll also drive users to move to the next action.

  • Active voice: ‘The client paid their invoice’

  • Passive voice: ‘The invoice was paid by the customer’

You can use the passive voice in some cases

Sometimes, we need to use the passive voice to put the most important information at the beginning of a sentence. Using the passive voice also avoids blaming users.

  • For example: ‘Your subscription hasn’t been paid’ instead of ‘You haven’t paid your subscription’.

American English

We use American English throughout the Mirakl platform. The following common words are spelled this way.

  • Organization

  • Canceled

  • Cancelation

  • Catalog

Capitalization

Use sentence case

It means that only the first word is capitalized unless it’s a proper noun.

Quote requests in progress

We don't use all caps. It's the written equivalent of shouting, and many people interpret it as aggressive. It's also much harder to read.

Contractions

A contraction is when two or more words are combined to form a new, shortened word.

Always use the long form of auxiliary verbs and avoid contracted forms.

  • Do not use abrasive cleaners.

  • If the unit is not functioning, check the contacts.

Directional language

Words like "above", "below", "left", and "right" are directional language. Avoid using them in your writing.

Here are some of the reasons why it shouldn’t be used:

  • Sometimes elements move around when screens are resized.

  • It requires being able to see the screen and, therefore, is inaccessible to users using screen readers.

  • It makes it harder to reuse strings and creates challenges for internationalization (for example, right to left languages).

File formats

Write file formats in uppercase.

  • CSV

  • HTML

  • XLSX

  • .csv

  • .html

  • .xlsx

Lists

Bulleted

Use in popovers if you have more than 2 items.

Use bullet points for lists of items.

For consistency, if you start a list with a verb, use the same structure for the other items.

Don’t use punctuation at the end of the different items and don't use numbered lists.

Modal verbs

Try not to use the following modal verbs, as they can confuse users:

  • may, might

  • could

  • should

  • would

Dates, numbers, and units

Dates

Local formatting is handled by Roma.

Nov 25, 2022

Mirakl uses the following format: Month + day, year

Start with the short version of the month, 3 letters.

Here is the list we use for month short version.

  • Jan

  • Feb

  • Mar

  • Apr

  • May

  • June

  • July

  • Aug

  • Sept

  • Oct

  • Nov

  • Dec

Times and timezones

Use the 12-hour clock time convention with AM or PM in capital letters. AM stands for Ante Meridiem, meaning before noon, and PM for Post Meridiem, meaning after noon.

  • 11:10 PM

  • 2:00 AM

To be more precise, you may want to display both date and time, for example, Nov 25, 2022, 11:10 PM.

Numbers

Numbers are easier to scan and read than their written form. Avoid writing out numbers as words.

Enter 10 in the Timeout field.

In English, use a period as a decimal separator and a comma for thousands.

This pen is €3.45.

250,000 operation hours

Pronouns

Don't assume the gender or biological sex of a user, use the generic pronoun 'they' instead of he or she.

Punctuation

Ampersands (&)

Use the word ‘and’ and not the ampersand (&). It’s a lot more accessible.

Commas

Use a comma to separate two different ideas in a sentence.

The machine is ready to start, but it is still on standby.

We use the Oxford comma, which is the final comma after “and” or “or” in lists.

Additional settings are shown for font, color, and brightness in the figure below.

Full stops

Don’t use full stop at the end of label, headers, titles, snackbar and so on.

When there are more than 2 sentences, you can add a full stop.

Full stops in links

Don’t use a full stop at the end of a link, unless it’s included in a sentence.

In that case, make sure the full stop isn’t part of the link

Want to know more about hyperlinks? Learn more in the hyperlink section

Use a comma before a conjunction in an enumeration (Oxford comma). Separate the last noun in a list from the rest of the list using a comma.

Additional settings are shown for font, color, and brightness in the figure below.

Additional settings are shown for font, color and brightness in the figure below.

Hyphens

Hyphens slow down reading and comprehension as words with hyphens tend to be longer to scan.

Consider rephrasing the sentence to avoid ambiguity.

This cereal has no sugar instead of This cereal is sugar-free

Be consistent. If you decide to use a hyphen, use it all the time.

Some words are never hyphenated:

  • back office (not back-office)

  • markup (not mark-up)

  • onboarding (not on-boarding)

Some always are:

  • drop-down

Tenses

Prefer simple tenses such as present, past, and future.

Avoid perfect tenses (have + past participle) and continuous tenses (be + verb-ing).

Past

You created a new store.

Present

Please enter a registered email address.

Future

The information will be lost.

Last updated