Don’t attribute human qualities to software or hardware.
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.
Use sentence case for most things.
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).
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.
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
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.
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.
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.
- 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
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.
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.
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”).
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.
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.”
Use British English spelling.
For questions of spelling, use the online Google Dictionary. Use the first spelling presented,
tagged British if relevant to that word. Favour
Use British English (colour, centre, etc). See a list of American and British English spelling differences here.
Commonly troublesome words
select, for checkboxes. Don’t call it a box.
press, for both buttons and links.
pressto press a button on the keyboard.
fill in, not
enter, for filling in a form field. See also Accessibility.markdown.
fill ina form; you don’t
fill it out(to fill out the form is to complete it. To fill in the form is to supply information as required.)
Upload file, not
Add new uploador
Add contact, not
Create new contactor
- 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
seea page, not
are taken toor
click through to
for example, not
say. e.g. is an acceptable abbreviation
the search bar
sectionfor a section of a page, not
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
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”).
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.
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 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.
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.
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 casein publishing).
real-time (adj.), real time (n.): Hyphenated when used as an adjective; not hyphenated when used as a noun.
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.):
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.
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.”
slideshow (n., adj.)
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:
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)
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.
wiki: Lowercase. Plural: wikis.
word-of-mouth (n., adj.): Note hyphens when used as a noun or adjective.