Skip to content

Latest commit

 

History

History
173 lines (112 loc) · 6.12 KB

style-guidelines.md

File metadata and controls

173 lines (112 loc) · 6.12 KB
Raw

The following are guidelines, not rules. Assess every situation case-by-case and use your judgement.

For branding and design guidelines, please use: Design Guidelines

Table of contents

  1. How we write
  2. Grammar and punctuation
  3. Links
  4. Lists
  5. Numbers
  6. Symbols, currency and abbreviations
  7. Common terms

How we write

Voice and tone

MetaBrainz speaks in a friendly, direct and easily understandable manner. We:

  • use plain, simple, language when possible
  • use short sentences
  • use an active voice (avoid the passive voice).

Spelling

We use US English. For instance:

  • color, not colour
  • organize, not organise.

Active and passive writing

Active writing mentions the subject (the person or thing 'doing' the action) first in the sentence (for example, inflation pushed up house prices).

Passive writing mentions the object (the person or thing 'receiving' the action) first. Passive sentences often include 'by' (for example, house prices were pushed up by inflation).

Active writing is more direct and should be used most of the time. We use short, clear sentences.

Grammar and punctuation

Exclamation marks

We avoid over-using exclamation marks in most instances — for instance, in documentation or page content.

Colon and semi-colons

When possible we’ll write 2 sentences instead, for ease of reading. Otherwise you use whatever fits best.

Apostrophes

We generally don’t add an extra 's' after nouns or names ending in 's'. For example: "The business’ work" – not "the business’s work."

We don’t use an apostrophe for dates, numbers, or plurals of abbreviations. For example: 1960s.

Bold

We rarely use bold – using too much will make it difficult for users to know which parts of your content they need to pay the most attention to. To emphasize words or phrases, we:

  • put key information at the start of sentences
  • use headings.

Capitals

We only use capitals for proper nouns, such as:

  • names of people, places and things, including buildings and brands
  • titles of books, albums, and recordings.

'Types' of places are not capitalized, unless referring to a specific place. For example: "I like the library" - and "I like Upper Hutt Library"

Generally, terms are not proper nouns, so should not be capitalized. Technical terms are not proper nouns. But if a word or term is branded as a distinct thing, treat it as a proper noun.

Headings

We use sentence case so only the first letter is upper case. We never link paragraph headings (we do link entity titles/headings).

Quotation marks

We use double quotation marks for:

  • exact quotations
  • direct speech.

We use single quotation marks for:

  • quotes inside quotes
  • technical terms, if deemed necessary (the first time it is used)
  • titles of documents or publications.

Links

We:

  • link to relevant content on our website before we link to external websites
  • never link paragraph headings (we do link entity titles/headings)
  • write descriptive links that tell you what you’ll find when you follow them - not 'click here'
  • links inside editing systems should always open in new tabs to not disrupt a user's workflow
  • we don't set links to open in a new tab or window in most other circumstances.

Lists

We use bulleted lists (coded as unordered lists) to list items or points, and numbered lists (coded as ordered lists) for processes where the order of steps is important.

We try to:

  • keep our lists short (2–7 items)
  • only use 1 level of nesting.

We use 2 types of bulleted lists – single-sentence lists and multi-sentence lists.

When we’re writing a single-sentence list, we:

  • start with a stem sentence that all the points have in common
  • start each point in lower case, and only use a full stop on the last point
  • don't use 'and' or 'or' at the end of the second-to-last point
  • check that each point makes a full sentence when read with the stem.

Multi-sentence lists are introduced by a complete sentence.

  • Each point in the list is also a complete sentence.
  • Each point can be 1–3 sentences long.
  • Each point begins with a capital letter and ends with a full stop.

Numbers

In general:

  • we usually use words for numbers from 0-9 and use digits for 10 and up
  • we use commas and no spaces to separate thousands when the number is over 10,000
  • when we’re talking about numbers in the millions, we use the word 'million' instead of writing out the number in full
  • we use spaces to separate groups of numbers when we write phone numbers.

Symbols, currency and abbreviations

Symbols

We use:

  • % – not 'percent' or 'per cent'
  • & – only if it’s part of a brand name
  • KB for kilobyte, MB for megabyte, and GB for gigabyte, for example 122 KB.

Abbreviations

If using abbreviations on a page, we expand them when we use them for the first time. For example: 'Welcome to MusicBrainz (MB)'.

To make our content easier to read, we avoid using:

  • e.g.
  • i.e.

These are often written in full, such as:

  • for example
  • such as
  • that is
  • and so on.

Common terms

We use two terms to refer to the people who interact with our data, sites and applications:

  • User/s: Everyone, including the below. When in doubt, use this widely understood term.
  • Editor/s: Users who contribute to or are part of the community.

To avoid confusion, use: MB = Musicbrainz, MeB = MetaBrainz

We refer to MetaBrainz sub-sites/brands as: Project/s

We have technical and development terminology that can have a different meaning to a casual user. In particular, please avoid using the term 'entity' in end-user messaging. The internal useage of this, and a number of other technical terms, is further explained in ticket MBS-12552.

Licence

These style guidelines are released under the Creative Commons Attribution-ShareAlike(BY-SA) 4.0 license. Based on https://www.data.govt.nz/about/about-data-govt-nz/our-style-guide/, by Te Kāwanatanga o Aotearoa, CC BY 4.0