Some general tidy up

guidelines/style-guidelines.md

@@ -0,0 +1,162 @@
+## Table of contents
+
+1. [How we write](#how-we-write)
+2. [Grammar and punctuation](#grammar-and-punctuation)
+3. [Links](#links)
+4. [Lists](#lists)
+5. [Numbers](#numbers)
+6. [Symbols, currency and abbreviations](#Symbols,-currency-and-abbreviations)
+7. [Common terms](#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 tense).
+
+#### Spelling
+
+We use US English.
+
+#### 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 don't use exclamation marks in most instances - for instance, we don't use exclamation marks in documentation or page content.
+
+#### Colon and semi-colons
+
+We avoid these. When possible we’ll write 2 sentences instead, or separate the clauses using a dash (with a space on either side).
+
+#### 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 emphasise 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, such as: of books, albums, recordings
+
+'Types' of places are not capitalized, unless referring to a specific place.
+For example: "I like the library" - and "I like my local Library"
+
+Generally, terms are not proper nouns, so should not be capitalised. 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 headings.
+
+#### Quotation marks
+
+We use double quotation marks for:
+* exact quotations
+* direct speech.
+
+We use single quotation marks for:
+* technical terms (the first time it is used)
+* classification descriptors
+* titles of documents or publications
+
+
+## Links
+
+We:
+* link to relevant content on our website before we link to external websites 
+* never link headings
+* write descriptive links that tell you what you’ll find when you follow them - not 'click here'
+* don't set links to open in a new tab or window, with exceptions to be decided case by case.
+
+
+## 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' on 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 use numerals instead of words when we write numbers – this helps you scan our content
+* 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.
+
+#### Currency
+
+We put both the currency code and currency symbol before any amounts of money we write.
+We don't use spaces between the code, symbol and amount.
+
+For example:
+* 'If you’re a United States citizen, you pay USD$640'.
+* 'If you’re an Australian citizen it costs AUD$890'.
+
+#### Abbreviations
+
+We expand all abbreviations when we use them for the first time on a page.
+For example: 'Welcome to MusicBrainz (MB)'.
+
+To make our content easier to read, we avoid using:
+* e.g.
+* i.e.
+* etc.
+
+These are often written in full, such as:
+* for example
+* such as
+* that is
+* and so on.
+
+
+## Common terms
+
+We refer to people who use our data, sites and applications as 'user'/'users'