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.
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.
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).
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.
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.
They’re great! They give your writing an informal, friendly tone. In most cases, use them as you see fit.
Emoji are a fun way to add humour and visual interest to your writing, but use them infrequently and deliberately.
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:
Write out big numbers in full. Only abbreviate them if there are space restraints, as in a chart: 1k, 150k.
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.
Use the % symbol instead of spelling out "percent".
When writing about currency, use the relevant currency sign before the amount.
Follow the local norm when writing telephone numbers.
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.
Use a hyphen between times to indicate a time period.
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
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.
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.
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
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 (...) 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 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 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.
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.
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.’”
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.
Don't use ampersands unless it's part of a company or brand name.
- Ben and Jeremy
- Ben & Jerry’s
People, Places, and Things
When referring generally to a file extension type, use all uppercase without a full stop. Add a lowercase s to make plural.
When referring to a specific file, the filename should be lowercase:
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.
- 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.
Slang and jargon
Write in plain English. If you need to use a technical term, briefly define it so everyone can understand.
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.