Grammar and formatting
Discover our key grammar principles.
Abbreviations
Use abbreviations consistently throughout your experience to help with predictability and usability. Do not make up your variants or notations. Write established technical abbreviations of long forms, names of organizations, and so on, consistently using uppercase letters.
USB cable
usb cable
Avoid abbreviations in Latin within sentences and write the English phrase instead.
Batch dosing is stopped during any interruption, for example, power supply failure or external stop.
Batch dosing is stopped during any interruption, e.g. power supply failure or external stop.
Avoid using short forms of words in sentences.
The maximum flow is reduced when the SlowMode function is enabled.
The max. flow is reduced when the SlowMode function is enabled.
Specific examples
Including/Excluding
Incl. tax
Excl. tax
Incl tax
Active and passive voice
In a sentence written in the active voice, the subject of the sentence acts. In a sentence written in the passive voice, the subject receives the action.
The active voice carries the same meaning as the passive voice, but it is shorter and more direct. Whenever possible, use the active voice rather than the passive voice.
Add the following line to the file.
The following line is to be added to the file.
In some cases, especially when we wish to emphasize the object modified by the action or we do not want to mention who is doing the action, use the passive voice.
Deleted users are removed from groups and can no longer access the platform.
We remove deleted users from groups, and they can no longer access the platform.
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 (uppercase letter for the first word of the sentence, then lowercase for all other words) when writing in Mirakl interfaces.
Quote requests in progress
Quote Requests in Progress
Contractions
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.
Don’t use abrasive cleaners
If the unit isn’t functioning, check the contacts.
Directional language
Avoid using words like above, below, left, or right in your microcopy. Actions and related descriptions should be close together to avoid using directional language. If you feel you need to add those words to your copy, reconsider the design of your page.
Adding directional language to your microcopy also makes it harder to reuse strings in a different context and creates challenges for internationalization (for example, right to left languages).
File formats
Write file formats in uppercase.
CSV
HTML
XLSX
.csv
.html
.xlsx
Formatting
Bold
Only use bold when referring to any UI element.
Lists
Bulleted
A bulleted list is preceded by a column. The structure of a bullet list must be consistent. If you begin the first bullet point with a verb, each bullet point on the list must start with a verb. Apply the same rule for nouns or any other kind of grammatical element.
Numbered
Use numbered lists to explain to users how to carry out a task or when priority in completing tasks matters. Never use numbered lists to enumerate a list of items (as for bullet lists).
Modal verbs
Whenever possible, do not use the following modals, as they can confuse users:
may, might
could
should
would
Dates, numbers, and units
Dates
For maximum clarity, use the 3-letter formatting for months, followed by day and year.
Nov 25, 2022
Official abbreviations for months:
Jan
Feb
Mar
Apr
May
June
July
Aug
Sept
Oct
Nov
Dec
As a secondary option and for space constraints, you may use the full numeral format (month, day, year).
11/15/22
Local formatting is handled by Roma.
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
02:00 AM
23:10
2am
Numbers
Enter 10 in the Timeout field.
Enter ten in the Timeout field.
Use a period as the decimal separator and a comma as the thousands separator in English.
250,000 operation hours
250.000 operation hours
Pronouns
Use they, not he or she.
Punctuation
Ampersands (&)
Do not use ampersands for accessibility reasons. Spell out the word and.
Commas
Use a comma to separate independent clauses from the rest of the sentence.
If the subordinate clause is independent of the main clause, place a comma before the conjunction. The comma indicates that there are two different ideas in the sentence.
The machine is ready to start, but it is still on standby.
The machine is ready to start but it is still on standby.
Use a comma to separate dependent phrases in front of the main clause. If the dependent phrase is in front of the main clause, place a comma between them. This improves readability.
Depending on the basic type selected, various options are available.
Depending on the basic type selected various options are available.
When there are several consecutive adjectives, and the adjectives are independent, separate them with commas.
If the adjectives can be separated using “and” or if the sequence of the adjectives can be changed without changing the meaning, then separate the adjectives using a comma.
Read-only files can be identified by the small, black, block icon.
Read-only files can be identified by the small black block icon.
Do not use a comma in front of an infinitive.
The individual parts of the support bar are coated with red paint to ensure that no part is left behind in the vehicle.
The individual parts of the support bar are coated with red paint, to ensure that no part is left behind in the vehicle.
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
Use hyphens to link words.
Five-year plan
Never use hyphens after adverbs.
Badly designed project
Badly-designed project
Always write attributive adjective compounds consisting of more than two words using a hyphen.
If the adjective compound consists of four or more words, place the hyphen so that the related adjectives are joined, and the adjective compound is sensibly structured.
On-the-fly solution
step-by-step instructions
low-voltage drop-out regulator
On the fly solution
step by step instructions
low voltage drop out regulator
low-voltage-drop-out regulator
No hyphen:
back office (not back-office)
markup (not mark-up)
onboarding (not on-boarding)
Hyphen:
drop-down
Tenses
You can use simple tenses within the Mirakl interface, meaning present, past, and future. Avoid perfect tenses (have + past participle) and continuous tenses (be + verb-ing).
Past
The information you entered will be lost.
The information you have entered will be lost.
Present
Enter a valid period.
Future
Note that this shipping price will only apply to new stores you create, not existing stores.
Note that this shipping price will only start applying to new stores you create, not existing stores.
Last updated