Grammar and Mechanics

Vocabulary

Maintaining a consistent vocabulary across Heartland’s products helps foster a shared mental model for us and our customers as they navigate our ecosystem. Whenever possible, try to use the same words for the same things.

Typically we can refer to our users as “users,” “employees,” “merchants’, “employers”, “customers,” etc.

Contractions

Contractions can be used to avoid having the language appear stilted. For instance, using “can’t” as opposed to “cannot” is an acceptable use in many circumstances.

Avoid awkward and overly casual contractions such as “that’ll” instead of “that will.” Try saying these out loud first and imagining them in a business situation before using them.

Abbreviations and Acronyms

In most cases, avoid using undefined acronyms. Use plain language wherever possible. Try and think the way that your customers would, and whether they will understand what the terms mean. If you use an acronym regularly, define it with the first use. For instance, “Payroll Based Journal (PBJ).”

Using acronyms and initialisms is acceptable when referring to entities or phrases that are more well-known in their acronym form, such as API, HTML, NASA, the BBC, etc.

Jargon vs. Plain Language

Be aware of your audience. Use of jargon is acceptable if your target audience uses industry specific terms frequently, but if there is a possibility that one person could be confused, it is better to spell things out clearly.

Example: “closure” is a concept specific to programming. It is a complex concept that need not be defined if the audience is developers.

Grammar

Be careful to not use nouns as verbs. For example “Setup” is a noun, but “Set up” is the active form.

Punctuation

  • Unless it’s part of a branded product name, spell out words such as “and” and avoid using an ampersand (”&”). They can be problematic for readability and may cause problems with internal search results.
  • Be careful to correctly use apostrophes, such as in contractions, or for possessive singular nouns. For possessive plural nouns, use the apostrophe after the last “s.”
  • Use the oxford comma when required.
  • If you find yourself using a semicolon (”;”) in a sentence, it may be becoming too long. In that case, consider breaking the phrase into two sentences unless it is necessary for the flow and does not overly extend the sentence.

Spelling

Use the American English spelling for all content, unless the product is to be displayed only in Britain and Canada.

Numbers

In most cases use numerals for representing numbers. When used in sentences, if the number is less than 10, it is often best to spell it out.
Negative numbers are shown in parentheses when they appear in a table format. For example, -$100 would be (100). When showing negative numbers in a sentence, use the minus sign. For example, -100.