• Immutable Page
• Info
• Attachments
• More Actions: Raw Text Print View Render as Docbook Delete Cache ------------------------ Check Spelling Like Pages Local Site Map ------------------------ Rename Page Delete Page ------------------------ Subscribe User ------------------------ Remove Spam Revert to this revision Package Pages Sync Pages ------------------------ Load Save SlideShow

< Launchpad UI wording guide

Canonical style guide

Note: This is a copy of the Canonical company style guide. It's here so that everyone can refer to it when writing for Launchpad. The Canonical personality, described below, applies to Launchpad. See the Launchpad UI text guidelines for Launchpad-specific rules.

The purpose of this style guide is to build your confidence in writing. It is not exhaustive, just a resource to help us all write in a consistent manner. While there is a lot of detail, including words and phrases to avoid and common style errors, there are a few general points to remember:

• Keep it simple
• Assume nothing
• Be consistent
• If you don't know, ask

Canonical-specific guidelines

Tone of voice

Mind your language!

Most of us will be responsible for producing written materials for Canonical at some point. With so many people representing the company, we need to make sure that our personality shines through.

The Ubuntu personality

Ubuntu is:

• Genuine
• Principled
• Accessible
• Reliable
• Playful
• Adventurous

Ubuntu is bold, exciting, different and accessible. While the copy we write should be clear and straightforward, it should also be friendly, conspiratorial and even irreverent. Our research shows that one of the most compelling features of Ubuntu is that it empowers users to choose a computing experience that suits them. People can really make it their own. Our written materials should reflect Ubuntu’s unique personality and the freedom and control it gives to new and existing users.

The Canonical personality

Canonical is:

• Adroit
• Reliable
• Precise
• Accessible
• Honest
• Personal

Business doesn’t mean boring. Yes, we’re smart and reliable, dedicated and precise. But we’re also accessible and friendly. As much as personalisation stands at the heart of Ubuntu, the personal touch is part of what makes Canonical different. We are friendly, approachable and straight-talking. Whether you’re talking to a CEO or a CIO, a systems administrator or a consumer, there’s no need to lose your personality in the process. It’s part of what makes you, and Canonical, special.

Things to remember

• Ubuntu and Canonical communications should be truthful, simple and relevant.
• We are straight-talking. No marketing guff. No technical jargon. Simplicity is everything.
• Write with the reader in mind. Consider what’s in it for them before you think about what’s in it for you. Who are your audience and what do they want to know?

UK or US English?

Canonical communications are generally written in UK English.

Frequent mix-ups include:

Using the term 'open source'

How to write 'open source' is always going to be a point of contention. However, in an effort to ensure consistency across Canonical, we're opting for the grammatically correct approach as defined below.

Only capitalise the term 'open source' when it's part of a name, for example, Open Source Initiative, Open Source Definition.

Only hyphenate 'open source' when it's an adjective followed by a noun, for example, 'open-source software', 'open-source community'.

Otherwise, please use lower case and two words, for example, 'open source is the way forward', ' I love open source'.

Naming conventions for our products and services

It can be easy to get in a muddle when referring to different Ubuntu products and services. If you're not sure how something should be described, check with the relevant product or service owner, or a member of the marketing team.

• Ubuntu should be referred to as 'Ubuntu', not 'Ubuntu Linux'.
• Ubuntu is used in 'countries' not 'markets'.
• Ubuntu is written with a capital U.
• Ubuntu is both a project and a product. Be clear about which one you mean.

Referring to a product by its full name throughout a document can make the text seem clumsy and awkward. You only need to use the full product name on its first mention in a document, then a simplified version in the remaining text. Examples of this include:

Headings

All headings should be sentence case. This means that you should only capitalise the first word.

• Use: Ubuntu reaches new heights
• Don't use: Ubuntu Reaches New Heights

Consistency

As we begin to establish common rules to follow across all Canonical communications, please try to stick to the below spellings:

• email
• online
• setup (noun), set up (verb)
• backup (noun), back up (verb)
• web
• website
• internet
• systems management
• virtualisation

If you don't have access to the style guide and you're having trouble remembering what our rules are, make sure that the spellings you use in a document are the same throughout. For example, if you begin a document referring to a website, every further reference should be the same.

Job titles

Use lower case for mid-sentence job titles.

• Use: Ubuntu makes life easier for systems administrators.

Use title case when indicating a quote source.

• Use: John Smith, Systems Administrator, Wikipedia

General best-practice guidelines

Apostrophes

Apostrophes can be separated into two clear categories: to show possession and to show that one or more letters have been missed out. Most of the confusion seems to arise with possession.

The main rule is that if the name or noun is in the singular, add an apostrophe (') followed by the letter 's'. If the name or noun is a plural ending in 's', simply add an apostrophe.

• Use: The player's house was burgled
• Use: The players' houses were burgled

The exception to this rule is it's and its. Remember: it's = it is, its = belonging to it (the possessive).

Another common mistake is you're and your. Remember: you're = you are, your = belonging to you.

Take a look at the 'Plurals and possessives' section for guidelines on writing plural acronyms.

Writing for the web

All of the above rules should apply to writing copy for the web. The following guidelines will also help you keep web users engaged and interested.

• Be succinct: write no more than 50 per cent of the text you would have used in a hard-copy publication. Short, punchy sentences are particularly important when writing for the web.
• Write for speedy scanning: don't ask users to read long blocks of text
• Use links wisely: make sure every link you include has a context. Click here is meaningless. The link should indicate what users can expect to find when they click on the link.

Active sentences

The average sentence length in any document should be between 15 and 20 words. A good way to keep sentences concise is to make them active rather than passive. Try to stick to a subject verb object sentence structure.

• Use: Fred joined the company today.
• Don't use: The company was joined by Fred today.

It's particularly important to keep your sentences simple when you're writing for the web. Just remember to get to the point, fast. People don't want to waste time filtering through waffle.

Words and phrases to avoid

Try to avoid jargon, long-winded phrases and words with negative connotations. Steer clear of the following:

• Allow - This suggests that we are in a position of power, permitting users or customers to conduct certain activities.
• The ability to – Use 'We can' instead of 'We have the ability to'
• Is able to – Use 'Ubuntu can' instead of 'Ubuntu is able to'
• Not only...but also...
• Eliminate
• Execute
• Terminate
• Kill
• Disruptive
• Explosive
• Leverage
• Ecosystem
• Going forward
• In order to
• Form factor
• Use case
• End user – Use 'user' instead
• Image
• Linux for human beings

It can be tempting to use flowery, official-sounding words rather than plain English. Try to keep it simple.

Confused words

Here is a list of words that often get confused. If you're not confident about their meanings, look them up.

Acronyms and abbreviations

Assume nothing. Just because you know what ERP means, and the people you’ve discussed it with know what it means, it doesn’t follow that the majority of your audience know. If you introduce unheard-of acronyms into your text without saying what they mean, your audience is likely to lose interest.

It is common practice to spell out acronyms unless they are in very common usage, for example BBC or IT. Write out the words in full before including the acronym in brackets.

Enterprise resource planning (ERP) is fine. But ERP (enterprise resource planning) makes the reader feel like they should already know what it means – don't make them feel stupid.

You should only spell out the acronym on its first mention in a document. After that, use the acronym exclusively. You can find out more about writing plural acronyms in the 'Plurals and possessives' section.

If we're going to reach a wider, non-technical audience, we need to make sure that our writing style is as accessible and inclusive as possible. We also need to respect the full names of other companies. As a result, try to avoid unnecessary abbreviations and remember to never abbreviate 'Microsoft' to 'MSFT', 'operating system' to 'OS' and 'and' to '&'.

Hyphens

Hyphens link words that form a composite adjective before a noun. Examples of adjectives formed from two or more words include:

• Computer-based work
• High-quality services
• Short-term goals
• Three-year-old child
• Real-time events (Real time is normally two words)
• Best-practice processes
• Open-source software (Open source is normally two words)

The presence or absence of a hyphen can easily change the meaning. Compare: 'The building has no smoking areas' to 'The building has no-smoking areas'.

Numbers

Numbers in single figures should be spelled out in most cases. From 10 onwards, numbers should be written in digits.

Exceptions to this rule include numbered lists and units of measurement.

When writing out numbers over the 100s, remember to include commas.

• Use: 7,000
• Don't use: 7000

Plurals and possessives

Ubuntu and Canonical should both be referred to as singular entities.

For example, use 'Canonical is' or 'Canonical has' not 'Canonical are' or 'Canonical have'.

Do not put apostrophes into decades or plural abbreviations.

• Use: The 1990s
• Don't use: The 1990's
• Use: Members of Parliament (MPs)
• Don't use: Members of Parliament (MP's)
• Use: Independent software vendors (ISVs)
• Don't use: Independent software vendors (ISV's)

However, phrases like two weeks' time and six months' leave do need apostrophes because they are possessive.

Lists

Vertical lists can be a great way of making dense information seem more digestible.

Traditionally, if you are continuing a sentence, you start each bullet with a lower case word followed by a semi-colon. To simplify the complexities of lists for everyone, this style guide recommends that all bulleted lists start with a capital letter as below.

Good writing tips include:

• Keep it simple
• Be consistent
• Assume nothing

Each bullet point should follow the same sentence structure. If the bullets are less than five words long, a full stop is not required.

Superlatives

Don't try to add impact to your work by using superlatives you cannot justify. Make sure of your facts before you use words such as:

Capitalisation of organisations

Random capitalisation can interrupt the flow of a sentence and irritate the reader. As a general rule, you should only capitalise words when written in conjunction with a name or organisation. Words like government, the administration and the cabinet should be lower case when on their own. Other examples include:

FAQs

There are some grammatical issues that can cause confusion. Here are some of the main offenders.

What is the difference between fewer and less?

Fewer means not as many, less means not as much.

A commonly-quoted example used to highlight the distinction is: 'There are fewer cars on the road, which means there is less traffic.'

Also compare: 'The fewer people know about this the better' and 'The less people know about this the better'.

Note: The rule does not work if the number is counted as a quantity or as a unit. For example: 'She paid less than ten pounds for it' or 'His last jump was less than fifteen feet'.

What is the difference between that and which?

This can, and has, caused many an argument so it's probably best not to get too worried about it. A useful guide is: that defines, which informs.

This is not a cast-iron rule but it can help: 'This is the house that Jack built, but I think the one next door, which Jack also built, is more attractive.'

'Which' is often clausal, so is predominantly preceded by a comma.

Compare 'The police stopped the second car that was driven by a woman' and 'The police stopped the second car, which was driven by a woman.'

Is it OK to split an infinitive?

There is no grammatical rule that says you can't split an infinitive. Sometimes, it is definitely better to split:

Can dot.com companies ever hope to fully recover their share values?

This sounds much better than moving 'fully' in front of 'to recover' or behind it. The key is not to write anything which is ambiguous or inelegant.

< Launchpad UI wording guide