Grammar and mechanics

#Abbreviations

#Latin abbreviations

Lowercase with periods. Note: it’s better to use real words if you have the space.

• etc. → and so on
• e.g. → for example
• i.e. → that is
• vs. → or, and, compared to

#Acronyms

Uppercase with no periods.

• Yes: SEO
• No: S.E.O.
• No: Seo

Make sure you explain unfamiliar acronyms with a tooltip. For longer copy, spell out the acronym in the first instance.

Avoid obscure acronyms (industry slang), and never attempt to coin your own.

• Yes: Single keyword ad group
• No: SKAG

#Common abbreviations

Common abbreviations are fine in microcopy (where space is limited), just don’t go overboard. Remember to put a period after the abbreviated word.

• Yes: Max. amount
• No: Max amount
• No: Mx. amt.

#Contractions

Don't be afraid to use them! It helps us sound conversational.

Exception: Use two separate words to emphasize issues and warnings.

• Yes: Images should not be larger than 1 MB
• No: This page isn't included in the sitemap

#Active vs. passive voice

Use the active voice as often as possible. This means focusing on the person doing the thing (the user), instead of the thing having something done to it. This helps users to understand whose responsibility it is to carry out a task.

• Yes: You need to update your preferences
• No: Your preferences need to be updated

Exception: Use the passive voice to avoid blaming or shaming users, especially when writing about issues.

• Yes: This thing was set up incorrectly
• No: You set this thing up incorrectly

Exception: Use the passive voice when the thing is more important (to the user) than the person doing the thing.

• Yes: Data is updated every Sunday
• No: Siteimprove updates your data every Sunday

#Capitalization

#What we capitalize (title case)

• Proper nouns (people, places, brand names)
• Siteimprove products and features (must be unique to the Siteimprove brand) such as:
  • Accessibility
  • DCI Score

#What we don't capitalize (sentence case)

• Menu items (except for products and features unique to Siteimprove)
• Concepts that aren't unique to the Siteimprove brand (like settings, notifications, issues, recommendations)
  • Edit settings
  • Turn off notifications
  • View issues
• Words like accessibility, performance, ads, when not referring to Siteimprove products
• Page headings at any level, unless the heading includes the name of a product or feature unique to Siteimprove
• Card titles, unless the heading includes the name of a product or feature unique to Siteimprove
• Pronouns (your, my) — except where the pronoun comes first such as "My Sites"

#Compound words

Compound words are created when you join two or more words together.

#When to hyphenate

• Compound adjectives that come before a noun. Example: This is a mobile-friendly site.
• Nouns that are created from a verb and a preposition
  • Yes: View all add-ons
  • Exceptions: Login, plugin

#When not to hyphenate

• Compound adjectives that come after a noun. Example: This site is mobile friendly.
• Phrasal verbs (verb and a preposition)
  • Yes: Sign up for a free trial
  • No: Sign-up for a free trial
• After the "re" prefix, unless a hyphen would improve readability
  • Yes: Recheck page
  • Exceptions: Re-examine, re-enter, re-emphasize

#Dates and times

#Dates

Date formats differ between markets. Pay close attention to commas and word order.

In North America, the month comes first.

• March 25, 2021
• Thursday, March 25, 2021
• 3/25/21

In Europe and Asia Pacific, the day comes first.

• 25 March 2021
• Thursday, 25 March 2021
• 25/3/21

Note: we do not include superscripts.

• No: March 25^th
• Yes: March 25

#Times

Use 12-hour format for North American and Asia Pacific markets and 24-hour format for all other markets.

#File extensions

When making a general reference to a file extension type, use all uppercase without a period. Add a lowercase s for plurals.

• Yes: GIF
• Yes: GIFs
• No: .gif

#Lists

Use a list to group related items or ideas in place of a longer paragraph. For more writing guidelines concerning lists, please see the component's guidelines section.

#Ordered list

Use an ordered list to communicate a specific priority, hierarchy, or sequence. Example:

1. Enter a search term
2. Hit Enter
3. See your results

#Unordered list

Use an unordered list when the order of the items is not important. Example: When you visit Copenhagen, you can:

• go on a canal tour
• try smørrebrød
• visit the Siteimprove HQ

#Names and titles

Address users by their first name in everyday emails and messages. Avoid using their name too much in the platform—this can come across as creepy.

• Hi Eddie
• Thank you, Mads!

#When to capitalize job titles (title case)

When referring to a specific person or department:

• Today’s webinar with Technical Writer Seán Needham
• Siteimprove’s award-winning Customer Success team

#When not to capitalize job titles (title case)

When referring to a general field or area of responsibility:

• This is a great product for marketing teams
• Calling all product designers!

#Nominalization

Nominalizations are abstract nouns created from verbs. A lot of words ending in “-tion” or “-ment” are nominalizations.

Avoid using these types of words in the UI — especially when writing about what the user can or should do. Be bold and use the verb instead. This should make your message clearer.

• Make optimizations → Optimize
• Take into consideration → Consider
• Add to approved words → Approve word

Exceptions: Static product and feature names.

• Keyword Discovery
• Landing Page Experience

Exception to the exceptions: Never attempt to invent your own nominalizations to describe new features or functionalities. If you’re having trouble naming something, ask your UX writer!

#Numbers and units

#Currency

#Symbol or acronym

In all currencies, place the symbol or acronym before the monetary amount.

• DKK 5,000
• $1.2 million
• €1

#Decimal separators

Most English-speaking countries use the decimal point:

• £1.75
• $16.50

Other markets (including most of Europe) may use a comma:

• £1,75
• $16,50

#Thousand separators

Most English-speaking countries use the comma to mark thousands:

• £525,000
• $63,789,004

Other markets may use a period or a space:

• €200.000 (Two hundred thousand euros)
• €200 000 (Two hundred thousand euros)
• €7.000.000 (Seven million euros)
• €7 000 000 (Seven million euros)

#Fractions vs. percentages

Use percentages (%) instead of fractions wherever possible. Fractions are harder to read and scan for, and they put extra cognitive load on the user.

• Yes: 75% of users
• No: 3/4 user
• No: Three-fourths of users

Exception: In longer copy, it’s okay to spell out fractions to emphasize interesting statistics (“One in ten people…”).

Always use the % symbol instead of spelling out "percent".

#Numerals

Use numerals in microcopy and headings. For longer content, spell out numerals from one to ten unless you’re referring to customer data or percentages.

• There are three things you can do on this page…
• …affects one in ten people…
• Less than 8% of…
• 1 of 5 items selected
• See results for 5 sites

#Units of measurements

For storage and memory, user uppercase letters with a space in between the number and the unit of measurement.

• 1 MB
• 500 KB

For dimensions, use lowercase letters with a space in between the number and the unit of measurement. There’s no need to include the unit of measurement twice.

• 500 x 500 px
• 60 x 60 cm

#Personal pronouns

• Use “you” and “your” as if you’re speaking directly to the user — this makes us sound more personable.
  • Yes: On this page, you can…
  • Maybe: On this page, it’s possible to…
  • No: On this page, users can…
  • No: On this page, our customers can…
• Use “we” and “our” when talking about Siteimprove (but try to keep our ego in check).
  • Yes: Someone from our Technical Support team will contact you.
  • No: Someone from our hardworking and dedicated Technical Support team will contact you.
  • Yes: Let us know how we can improve this feature.
  • No: Our team has worked so hard to bring you this feature. Please let us know if you think it could be improved, and we’ll try our best to consider your request.
• Avoid using gendered pronouns (he, him, his, she, her, hers). Usually, it’s quite easy to drop the pronoun altogether.
  • No: Enter his or her full name
  • Maybe: Enter their full name
  • Yes: Enter the user’s full name

#Place names

Always keep our global audience in mind. Spell out city, state, and country names to avoid ambiguity.

• Yes: California
• Yes: Canada
• No: CA

For countries with common abbreviations, you can spell out the name in the first instance and use the abbreviation in subsequent mentions.

• United States (US)
• European Union (EU)
• United Kingdom (UK)

#Plain language

Our users come from different backgrounds and cultures. We want to be as accommodating as possible, regardless of their language skills and technical abilities.

• Use simple, familiar words to describe things
• Only use technical terms if it’s really necessary
• Keep explanations concise, and sentences short

#Punctuation

This section features guidelines for the following punctuation marks:

• Ampersand
• Apostrophe
• Colons
• Comma
• Dashes and hyphens
• Ellipses
• Exclamation points
• Question marks
• Quotation marks
• Semicolons

#Ampersand

Only use an ampersand if it belongs in a brand name. Otherwise, spell out “and”.

• Yes: Search and replace
• No: Search & replace

#Apostrophe

#When to use an apostrophe

• To show possession
  • Singular: Siteimprove's birthday
  • Words ending with s: James's PPC ads
  • Plural: visitors' names
• For common contractions
  • Yes: do not → don’t
  • Yes: cannot → can’t
  • Yes: it is → it’s
  • And so on

#When not to use an apostrophe

• After acronyms
  • Yes: JPGs
  • No: JPG's
• For quotes (use double quotation marks instead)

#Colons

Note: Use colons sparingly!

#When to use a colon

• To introduce a list. Example: Siteimprove Policy can help you manage all areas of your website: style guides, legal policies, brand guidelines, and more.
• To emphasize a point. Example: The most important thing: proper colon use.

#When not to use a colon

• In the middle of a command or action
  • No: Go to: My Sites
  • Yes: Go to My Sites
• To separate labels from dropdowns or form fields
• To introduce sections in longer copy — use a subheading instead
• To highlight dynamic content — use bold formatting instead
  • No: Manage settings for: Cathy's campaign
  • Yes: Manage settings for Cathy's campaign

#Comma

We use the Oxford comma — a comma before the word “and” at the end of a list.

• Yes: Siteimprove's core values are to be people-centric, passionate, and innovative.
• No: Siteimprove's core values are to be people-centric, passionate and innovative.

#Dashes and hyphens

#Em dash (—)

Em dashes help us sound conversational, and can make longer copy easier to scan. Use an em dash, by writing — in HTML, to:

• interrupt a thought
• break up a complex sentence
• emphasize a conclusion

Example: We need you to tell us about the purpose, context, or meaning of different page elements — in other words, information that only a human being can provide.

#En dash (–)

En dashes are used to show a range of dates or times. Create one by writing – in HTML.

Example: Visit us July 4–8 between 7–10 a.m.

#Hyphen (-)

Hyphens are used to:

• create compound words
• improve the readability of prefixed words
  • Yes: Re-examine
  • No: Reexamine (sounds like a medication)

#Ellipses

Use sparingly, and never to create a sense of drama or suspense.

Use them in a quote or code snippet to indicate you're omitting something. Offset by a space on either side.

Example: "It's allowed us to make improvements we didn't even know existed, … saving us time and enabling us to govern our pages more strategically," he said.

#Exclamation points

Use sparingly, and never in a headline or button!

#Periods

#When to use periods

• At the end of full sentences (descriptions, tooltips, Learn components)
• In Latin abbreviations: e.g. etc.
• See decimal separators

#When not to use periods

• In headings and titles
• In microcopy (button text, labels, dropdowns)

#Question marks

Questions should be used sparingly in the UI.

Avoid rhetorical questions, and never “ask” questions on behalf of the user — these are often more confusing than helpful.

• No: Why is SEO important?
• No: What’s the worst that could happen?

It’s fine to ask questions if we're asking for confirmation or user input. Example: Delete this Activity Plan?

Exception: Help Centre article titles are often phrased as questions. This is acceptable because users are actively searching for answers (and not just trying to navigate the platform).

#Quotation marks

• Punctuation goes inside quotation marks of a direct quote. Example: "Siteimprove is the best!" said Morten.
• Punctuation goes outside quotation marks when not part of a direct quote. Example: Have you heard of "digital certainty"?
• Use singular quotation marks for quotes within quotes. Example: "We've been told to ‘keep up the good work’" said Torben.

#Semicolons

Use sparingly. If you have the urge to use a semicolon, it might indicate that the sentence is too complex for the average reader.

#US vs. UK English

Our source language is American English.

If you’re unsure about spelling (“is it email or e-mail?”), you can check the AP Stylebook. Ask your UX writer for login details