Writing: Grammar and Mechanics

Sticking to certain rules of grammar and mechanics helps us keep our writing clear and consistent. This section will lay out the house Decoded style, which should apply to all of our content.

Basics

Write for all readers. Some people will read every word you write. Others will just skim. Help everyone read better by grouping related ideas together and using descriptive headers and subheaders.

Focus your message. Create a hierarchy of information. Lead with the main point or the most important content, in sentences, paragraphs, sections, and pages.

Be concise. Use short words and sentences. Avoid unnecessary modifiers.

Be specific. Avoid vague language. Cut the fluff.

Be consistent. Stick to the copy patterns and style points outlined in this guide.

Guidelines

Abbreviations and acronyms

If there’s a chance your reader won’t recognise an abbreviation or acronym, spell it out the first time you mention it. Then use the short version for all other references. If the abbreviation isn’t clearly related to the full version, specify in parentheses.

  • First use: Application Programming Interface (API)
  • Second use: API

If the abbreviation or acronym is well known, like EST or GMT, use it instead (and don’t worry about spelling it out).

Active voice

Use active voice. Avoid passive voice.

In active voice, the subject of the sentence does the action. In passive voice, the subject of the sentence has the action done to it.

  • Yes: Felicity logged into the computer.
  • No: The computer was logged into by Felicity.

Words like “was” and “by” may indicate that you’re writing in passive voice. Scan for these words and rework sentences where they appear.

One exception is when you want to specifically emphasise the action over the subject. In some cases, this is fine.

  • Your account was flagged by our abuse team.

Capitalisation

We use a few different forms of capitalisation. Title case capitalises the first letter of every word except articles, prepositions, and conjunctions. Sentence case capitalises the first letter of the first word.

When writing out an email address or website URL, use all lowercase.

Don't capitalise random words in the middle of sentences. Here are some words that we never capitalise in a sentence. For more, see the Word List.

  • website
  • internet
  • online
  • email

Contractions

They’re great! They give your writing an informal, friendly tone. In most cases, use them as you see fit.

Emoji

Emoji are a fun way to add humour and visual interest to your writing, but use them infrequently and deliberately.

Numbers

Spell out a number if it is less than or equal to ten in value. Otherwise, use the numeral.

  • Ten new learners started on Monday, and 12 start next week.
  • I drank three cups of tea at the airport.

Numbers over 3 digits get commas:

  • 999
  • 1,000
  • 150,000

Write out big numbers in full. Only abbreviate them if there are space restraints, as in a chart: 1k, 150k.

Dates

Spell out the day of the week and the month, and use the following sequence: Day Date Month. Use plain numbers rather than the suffix -th or equivalent.

  • Yes: Friday 24 September
  • No: Friday September 24th

Decimals and fractions

Spell out fractions.

  • Yes: two-thirds
  • No: 2/3

Use decimal points when a number can’t be easily written out as a fraction, like 1.375 or 47.2.

Percentages

Use the % symbol instead of spelling out "percent".

Money

When writing about currency, use the relevant currency sign before the amount.

  • $10,000
  • £10,000
  • €10,000

Telephone numbers

Follow the local norm when writing telephone numbers.

Time

Use numerals, and don’t use minutes for on-the-hour time.


You can use either the 12- or 24-hour clock, depending on what is most culturally relevant to your reader. If you're using the 12-hour clock, write am or pm in lowercase.

  • 7am

  • 7:30pm
  • 07:00
  • 19:30

Use a hyphen between times to indicate a time period.


  • 7am-10:30pm

Specify time zones when writing about a meeting or event, or something else people would need to schedule.

Abbreviate decades when referring to those within the past 100 years.

  • the 00s
  • the 90s

When referring to decades more than 100 years ago, be more specific:

  • the 1900s
  • the 1890s

Punctuation

Apostrophes

The apostrophe’s most common use is making a word possessive. If the word already ends in an s and it’s singular, you also add an ‘s. If the word ends in an s and is plural, just add an apostrophe.

  • The biscuit thief ate Bella’s biscuit.
  • The biscuit thief ate Franklin’s biscuit.
  • The biscuit thief ate the managers’ biscuit.

Colons

Use a colon (rather than an ellipsis, em dash, or comma) to offset a list.

  • Erin ordered 3 kinds of biscuits: glazed, chocolate, and pumpkin.

You can also use a colon to join two related phrases.

  • I was faced with a dilemma: I wanted a biscuit, but I’d just eaten a brownie.

Commas

When writing a list, use the serial comma (also known as the Oxford comma).


  • Yes: Ian admires his parents, Oprah, and Gary Barlow.
  • No: David admires his parents, Oprah and Gary Barlow.

Otherwise, use common sense. If you’re unsure, read the sentence out loud. Where you find yourself taking a breath, use a comma.

Dashes and hyphens

Use a hyphen (-) without spaces on either side to link words into single phrase, or to indicate a span or range.


  • first-time learner
  • Monday-Friday

Use an em dash (—) to offset an aside.

Use a true em dash, not hyphens (- or --).

  • Jamal thought Sophia was the biscuit thief, but he was wrong — it was Cornelius.

Ellipses

Ellipses (...) can be used to indicate that you’re trailing off before the end of a thought. Use them sparingly. Don’t use them for emphasis or drama, and don’t use them in titles or headers.

  • “Where did all those biscuits go?” Jermaine asked. Cornelius said, “I don't know...”

Ellipses, in brackets, can also be used to show that you're omitting words in a quote.

  • “When in the course of human events it becomes necessary for one people to dissolve the political bands which have connected them with another and to assume among the powers of the earth, [...] a decent respect to the opinions of mankind requires that they should declare the causes which impel them to the separation.”

Full stops

Full stops go inside quotation marks. They go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.

  • Jordan said, “I ate a biscuit.”
  • I ate a biscuit (and I ate a brownie, too).
  • I ate a biscuit and a brownie. (The biscuit was Sandra’s.)

Leave a single space between sentences.

Question marks

Question marks go inside quotation marks if they’re part of the quote. Like full stops, they go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.

Exclamation points

Use exclamation points sparingly, and never more than one at a time. They’re like high-fives: a well-timed one is great, but too many can be annoying.

Quotation marks

Use quotes to refer to words and letters, titles of short works (like articles and poems), and direct quotations.

Full stops and commas go within quotation marks. Question marks within quotes follow logic — if the question mark is part of the quotation, it goes within. If you’re asking a question that ends with a quote, it goes outside the quote.

Use single quotation marks for quotes within quotes.

  • Who was it that said, “A fool and his biscuit are easily parted”?
  • Ayesha said, “A wise man once told me, ‘A fool and his biscuit are easily parted.’”

Semicolons

Go easy on semicolons. They usually support long, complicated sentences that could easily be simplified. Try an em dash (—) instead, or simply start a new sentence.

Ampersands

Don't use ampersands unless it's part of a company or brand name.

  • Ben and Jeremy
  • Ben & Jerry’s

People, Places, and Things

File extensions

When referring generally to a file extension type, use all uppercase without a full stop. Add a lowercase s to make plural.

  • GIF
  • PDF
  • HTML
  • JPGs

When referring to a specific file, the filename should be lowercase:

  • slowclap.gif
  • ben-twitter-profile.jpg
  • ilovebiscuits.html

Pronouns

If your subject’s gender is unknown or irrelevant, use “they,” “them,” and “their” as a singular pronoun. Use “he/him/his” and “she/her/her” pronouns as appropriate. Don’t use “one” as a pronoun.

For more on writing about gender, see Writing about people.

Names and titles

The first time you mention a person in writing, refer to them by their first and last names. On all other mentions, refer to them by their first name.

Capitalise the names of departments and teams (but not the word "team" or "department").

  • Marketing team
  • Support department

Capitalise individual job titles when referencing to a specific role. Don't capitalise when referring to the role in general terms.

  • Our new Project Manager starts today.
  • All the managers ate biscuits.

Don't refer to someone as a “ninja,” “rockstar,” or “wizard” unless they are literally a ninja, rockstar or wizard.

URLs and websites

Capitalise the names of websites and web publications. Don’t italicise.

When you need to spell out a URL, leave out the http://www.

Writing about Decoded

Always capitalise the “D” in Decoded. Never capitalise the “C”.

Refer to Decoded as “we,” not “it.”

Use title case when writing the proper names of Decoded products, experiences and tools.

  • Hacksy
  • Code in a Day
  • Data Fellowship

Writing about other companies

Honour companies’ own names for themselves and their products. Go by what’s used on their official website.

  • iPad
  • YouTube
  • Yahoo!

Slang and jargon

Write in plain English. If you need to use a technical term, briefly define it so everyone can understand.

Write positively

Use positive language rather than negative language. One way to detect negative language is to look for words like “can’t,” or “don’t”.

  • Yes: To get a cup of tea, join the queue.
  • No: You can’t get a cup of tea if you don’t join the queue.