Anthropomorphism

Don’t attribute human qualities to software or hardware.

Examples

• Don’t: Add your ISBN so that Consonance can include it in ONIX.

• Do: Add your ISBN so that it is included in ONIX.

• Don’t: Consonance will take your file and upload it.

• Do: Your file uploads.

Capitalisation

Use sentence case for most things.

People

Capitalise a person’s title only when it’s used directly before a name. This rule includes titles pertaining to government positions (like president, senator, mayor, ambassador, chief justice), religious positions (like pope, cardinal, rabbi), and other organisational positions (like chair, treasurer, general manager).

Examples

• Emma Barnes is the founder and chief executive officer of General Products.

• General Products Founder and Chief Executive Officer Emma Barnes.

• She was appointed ambassador to the United Nations by President Obama.

• Pope Benedict XVI succeeded Pope John Paul II.

Never prefix a woman’s title with female, such as Emma Barnes is the female founder and chief executive officer of General Products.

Terms

Within sentences, do not capitalise publishing topics or system features such as printing, social media, marketing, press release, advance information sheets, contracts, etc. These are not proper nouns and, therefore, should not be capitalised. An exception is when these nouns refer specifically to paid applications. In these cases, the word “app”, “report” or “tasks” is not capitalised, but the name of the app is capitalised.

Titles of published works: blog posts, books, articles, documentation articles and so on.

Never use title case. Capitalise the first word.

Do not capitalise subheadings in articles.

Company and product names

Follow an organisation’s conventions as to how it capitalises and punctuates its names. Many organisations (for example, FedEx) incorporate intercaps, or capital letters in the middle of the name. Other organisations, such as Yahoo!, incorporate punctuation characters in their names. Some examples include:

• iPod shuffle
• IHOP
• PayPal
• Visa
• MasterCard

In some cases, you may not be able to replicate a graphic symbol used in a name. WALL·E, for instance, is difficult to reproduce and is generally spelled with a hyphen. When in doubt, look at some of the organisation’s press releases or at its copyright page if it has one.

For company, product, and website names that use all-lowercase letters, use an initial capital letter as you would for most other proper nouns. Otherwise, the names are hard to distinguish in text. For company names that include a capital letter somewhere (like eBay or iPod), follow the company’s capitalisation in most situations—even an internal capital letter will alert the reader that the word or phrase is a proper noun.

Clause order

Put conditional clauses before instructions, not after.

If a sentence describes both an objective and the action needed to achieve that objective, start the sentence with the objective.

• Don’t: Browse or use the search to go to the work’s page.

• Do: To go to the work, browse or use the search.

Hyphens

Hyphenate words only when needed for clarity.

Hyphenated compounds in titles

If a hyphenated compound appears in title-style capitalisation, capitalise the first word, and capitalise all subsequent words in the compound except for articles (a, an, and the), prepositions of three or fewer letters (like to and of), and coordinating conjunctions (for, and, nor, but, or, yet, and so). Ask yourself: If this word weren’t in a hyphenated compound, would I capitalise it? If the answer is yes, capitalise it as part of the hyphenated compound, too.

Examples

• The big spender’s budget how-to
• Author of how-to book on bee-keeping prone to anaphylaxis
• Governor slams eBook about her re-election campaign

Prepositions

Use prepositions as needed, even at the ends of sentences.

There’s no rule against placing a preposition at the end of a sentence. Place the preposition where it makes most sense and makes the sentence easiest to read.

• Don’t: For details, see the user documentation for the section with which you’re interacting.

• Do: For details, see the user documentation for the section you’re interacting with.

Present tense

Avoid will.

Write in the present tense: Returns a page that…, You land on the works page, rather than Returned a page that… or Will return a page that…, or You’ll land on the works page.

Write simple, declarative sentences. Brevity is a plus: get to the point.

• Don’t: This will improve findability on the web.

• Do: This improves findability on the web.

• Don’t: This check cannot run because a short description has not been added to this product.

• Do: This check cannot run because this product does not have a short description.

• Don’t: When the page refreshes you will be able to edit them.

• Do: When the page refreshes, edit them.

Pronouns

Ensure that a pronoun clearly refers to its antecedent (the noun that it’s replacing).

Pronouns referring to companies

When referring to General Products or to another company, use the third-person singular pronouns it and its. In the United States, a company is treated as a collective noun and requires a singular verb and a singular pronoun. In the UK, the convention is less strict, but at General Products we adhere to the singular form.

The company anticipates an increase in its third-quarter spending (singular verb, singular possessive “its”).

Hypothetical people

When using pronouns in reference to a hypothetical person, such as a user with a session cookie, user gender neutral pronouns (they/their/them). Instead of:

• he or she… use they.
• him or her… use them.
• his or her… use their.
• his or hers… use theirs.
• himself or herself… use themselves.

Ensure that a pronoun clearly refers to its antecedent

• Don’t: Once a contract template has been used on a contract, it can’t be edited.
• Do: Once a contract template has been used on a contract, the template can’t be edited.

Second person

Use you rather than we.

Don’t say we, or we recommend. Lead our users to think about interacting with the app, not the people behind the curtain.

Use the second person: “you” not “we”. If you need to refer to the team, say ‘Consonance’ using the ‘< %= app_name % >’ method.

• Don’t: “We recommend that you enter the edition number.”

• Do: “Enter the edition number.”

Spelling

Use British English spelling.

Google dictionary

For questions of spelling, use the online Google Dictionary. Use the first spelling presented, tagged British if relevant to that word. Favour colour over color.

Use British English (colour, centre, etc). See a list of American and British English spelling differences here.

Word list

Commonly troublesome words

Verbs

• Use choose, not select or pick.
• Use tick, not check or select, for checkboxes. Don’t call it a box.
• Use click, not click on or hit or press, for both buttons and links.
• Use press to press a button on the keyboard.
• Use fill in, not type or add or enter, for filling in a form field. See also Accessibility.markdown.
• You fill in a form; you don’t complete it, or fill it out (to fill out the form is to complete it. To fill in the form is to supply information as required.)
• Use Upload file, not Add new upload or Upload import
• Use Add contact, not Create contact or Create new contact or New contact
• Where there are two actions, add them with a conjunction e.g. Upload and validate
• Where the object doesn’t exist in the real world, don’t add it (because it doesn’t exist). Instead use New import.
• You see a page, not go to or are taken to or land on or arrive at
• Use Go to not navigate to or click through to
• Use for example, not for instance or say. e.g. is an acceptable abbreviation

Nouns

• Use spreadsheet not XLSX
• Use the search bar
• Use page, not screen
• Use section for a section of a page, not part or card

Words to use when describing the interface

Acceptable abbreviations, business and technical terms, idioms

• alt text: Short for alternative text, which is text entered into the HTML alt attribute associated with an image on a web page.

• app: Short form of application. Plural: apps. Do not use if there’s any room for confusion.

• B2B: Abbreviation for business-to-business.

• BA: Abbreviation for bachelor of arts. No periods.

• best-seller (n.), best-selling (adj.): Note hyphen.

• beta: Capitalise beta if it is part of an official product name. Otherwise, lowercase it.

  • Sign up for the new Yahoo! Messenger beta.

• blog (n., adj., v.): Preferred to weblog. (lowercase)

• business-to-business: hyphenated (abbreviation: B2B)

• call-to-action, calls-to-action, CTA, CTAs: Always hyphenate when used as a noun (as in “call-to-action” or “calls-to-action”) or an adjective (as in “call-to-action button” or “call-to-action manager”).

• camera phone: Two words.

• change log: To be honest, we prefer it as one word, but we have legacy uses of it as two. Since it’s controversial, aim to use an alternative word, such as news or updates.

• checkin (n.) check-in (adj.), check in (v.): Never one word, even when used as a noun or an adjective. Two words when used as a verb.

• cell phone (n., adj.): Two words, no hyphen.

  • He left the message on my cell phone.

• clickthrough (n., adj.), click through (v.): One word when used as a noun or an adjective. Two words when used as a verb.

  • The company’s online ads consistently earn a high clickthrough rate.
  • Click through to the last page to see your score.

• crowdsource, crowdsourcing: One word.

• do’s and don’ts: Note the apostrophes. This is AP style. However, it will always cause the editors in your readership to have blinding migraines and send you hate mail, so try to avoid using this construction if at all possible.

• dropdown adj.: Never hyphenate.

• e.g.: Abbreviation meaning for example. Note periods. Don’t include a space after the first period. OK to use when space is a consideration; otherwise, use for example, for instance, or such as.

  • Instead of using and capitalising at the start of a sentence, use For instance.
  • If used, always include a comma after the last period. See also “i.e.” and “ex.” as each of these has different meanings and are not interchangeable.
  • Enter a search term (e.g., recipes, horoscopes, gifts) into the box.

• ebook: All lowercase (in titles/headlines and at the beginning of sentences, capitalise the “e” but not the “b”).

• ecommerce

• email (n., adj., v.): One word, no hyphen. Plural: email messages and emails are both acceptable.

• geolocation: One word. The geographic location of an internet connected computer, or the process of determining that location.

• geotagging (n.), geotag (v.): One word. The verb means to add geographic data (such as longitude and latitude coordinates) to a photo or other media file.

• Google: According to Google guidelines, it is not okay to use this trademark as a verb. Use search, search for, or search on instead.

• handheld (n.), hand-held (adj.): The noun refers to a personal digital assistant, or PDA.

• hashtag

• homepage

• how-to (n., adj.): Note hyphen when used as a noun or an adjective. Plural noun: how-tos.

• ID: Abbreviation for identity. Abbreviation is always acceptable.

• i.e.: Abbreviation meaning that is. Note periods. Don’t include a space after the first period. Okay to use when space is a consideration; otherwise use that is, in other words, or equivalent. If used, include a comma after the last period. (Note that “i.e.” does not have the same meaning as “e.g.”)

• in-house: Always hyphenated.

• inbound marketing: Lowercase.

• internet: Lowercase.

  • internet marketing

• ISNI: Abbreviation for International Standard Name Identifier. Abbreviation is always acceptable.

• IT: Abbreviation for information technology. Abbreviation is always acceptable.

• keyword, key word (n.): One word when referring to terms that are used on a web page to optimise it for search engines. Use two words in other cases — for example, when key is a synonym for primary or most important.

  • An SEO specialist can help you determine the best keywords to use on your web page.
  • She heard little else that he said; the key word in the sentence was “love.”

• latest Use in favour of ‘current’.

• mashup (n., adj.), mash up (v.): One word when used as a noun or an adjective. Two words when used as a verb.

  • Anyone can create a mashup with the right technology.
  • Use our tool to mash up RSS feeds into a single view.

• MBA: Abbreviation for master of business arts. No periods.

• metadata (n.)

• LinkedIn

• login (n., adj.); log in, log in to (v.): One word when used as a noun or an adjective. Two words when used as a verb, which may be followed by the preposition to. Note that sign in is preferred because it sounds less technical.

• news feed (n.)

• news release: Use instead of “press release” whenever possible.

• nonprofit

• OK (n., v., adv.): To be used interchangeably with okay. Do not use variations such as Ok and o.k., which are incorrect.

• opt-in (n., adj.), opt in (v.): Hyphenated as a noun or an adjective. Two words as a verb.

  • The opt-in has been disabled.
  • To receive electronic statements, you must opt in.

• ORCID: Always presented uppercase: no lowercase i.

• page view: Two words. The viewing of a web page by one visitor.

  • Advertisers consider how many page views a site receives when deciding where and how to advertise.

• pay-per-click: Hyphenated (do not use the abbreviation PPC as that can also mean printed paper case in publishing).

• real-time (adj.), real time (n.): Hyphenated when used as an adjective; not hyphenated when used as a noun.

• retweet

• RSS: Acronym for Really Simple Syndication. All capitals. Abbreviation is always acceptable, but avoid using RSS on its own, since few people know what it means. Use news feed, RSS news feed, or RSS reader as appropriate.

• P&L: Stands for P&L. Abbreviation is always acceptable.

• plugin (n., adj.), plug in (v.):

• podcast

• pop-up (n., adj.), pop up (v.): Note hyphen when used as a noun or adjective. Not popup. Two words when used as a verb. Get rid of pop-ups before they pop up. Stop pop-up ads from ever annoying you again.

• PPC: Abbreviation for pay-per-click. Can be conflated with printed paper case, so only abbreviate in context.

• salesperson, salespeople

• screen capture

• screencast

• screen name

• screenshot

• SEO: Abbreviation for search engine optimization.

• setup (n., adj.), set up (v.): One word when used as a noun or an adjective. Two words when used as a verb. It is clunky, so prefer not to use it as a noun.

  • Set up your Yahoo! store.
  • Check your Yahoo! store setup.
  • Your setup fee has been waived.

• sign-in (n., adj.); sign in, sign in to (v.): As a noun or an adjective, it’s hyphenated. As a verb, it’s two words, which may be followed by the preposition to.

  • All visitors must sign in on the sign-in page.
  • Visitors can sign in to Yahoo! Mail automatically.
  • Choose your preferences for sign-in and security.

• sign-out (n., adj.); sign out, sign out of (v.): As a noun or an adjective, it’s hyphenated. As a verb, it’s two words, which may be followed by the preposition of.

• sign-up (n., adj.), sign up (v.): Hyphenate when used as a noun or an adjective. Two words when used as a verb. Prefer this over log in or login.

  • Sign up for the service.
  • Fill in the sign-up form.
  • Sign-up is free.

• since: Not a synonym for “because.” Can be confused with the sense of “over the time that has passed” rather than “as a result of.” Use “because” instead of since when possible. Also applies to “due to” and “owing to” and “due to the fact that” and other, needlessly wordy ways of saying “because.”

• site map

• slideshow (n., adj.)

• smartphone

• SME: Abbreviation for small and medium-size enterprises (plural: SMEs).

• SMO: Abbreviation for social media optimization.

• social CRM: The word “social” here is lowercase. Abbreviation for social customer relationship management, usually in regard to software platforms.

• social network (n.), social-network (adj.): Two words when used as a noun. Note hyphen when used as an adjective.

  • Social-network analysis is a key technique in modern sociology.
  • Add contacts to expand your social network.

• social networking (n.), social-networking (adj.): Note hyphen when used as an adjective. Two words when used as a noun.

  • The social-networking phenomenon has really taken off.
  • To attract users, the site added social networking.

• software-as-a-service: Lowercase; hyphenated (abbreviation: SaaS).

• spam (n., adj., v.): Lowercase when referring to unsolicited email or the act of sending such email.

• startup (n., adj.), start up (v.): One word when used as a noun or an adjective (not hyphenated). Two words when used as a verb.

• swag: Free goods. Not schwag or shwag.

• text (n., v.): Short form of text message. Plural: texts. Other forms:

• texted, texting.

• Did you get my text?

• Don’t text while driving.

• She was texting during the lecture.

• text message (n.): Two words when used as a noun. Note hyphen when used as an adjective or a verb.

  • She had a heated text-message argument with her boyfriend.
  • Did you get my text message?
  • I’ll text-message you with the details.

• touchscreen (n., adj.)

• toward (not towards)

• tweet

• Twitter

• video camera

• videoconference

• voicemail: One word, lowercase. Not voice mail.

• URL: All capitals. Stands for Uniform Resource Locator. Abbreviation is always acceptable. Plural: URLs.

• UK: Abbreviation for United Kingdom. Not U.K. or U. K.

• U.S. (n., adj.): Abbreviation for United States. Note periods, no space. Not US or U. S. The single exception is specifying currency in prices; in this case, do not include the periods.

  • US $299

• USA: Abbreviation for United States of America. Abbreviation is always acceptable.

• username: Lowercase, one word.

• web (n., adj.): Lowercase.

• webcam

• webcast

• webhook

• webinar

• web page

• website

• whitepaper

• wiki: Lowercase. Plural: wikis.

• word-of-mouth (n., adj.): Note hyphens when used as a noun or adjective.