Language and grammar

Use conventions to make your writing consistent, clear, and specific.

Acronym or initialism?

This is probably just grammar pedantry at its worst, but the main difference is that an acronym can be spoken as a complete word, and an initialism can’t. So NASA is an acronym, but JPL is an initialism.

Active or passive voice?

The answer to this is easy: Active! However, trying to work out which one you have on the page in front of you is not so easy, so here’s a quick trick: try adding “by zombies” to the end of your sentence. If it makes sense, your sentence is passive. Here’s a worked example for you: “The button is pressed” by zombies (Makes sense! Must be passive), rewrite to “press the button”.

Bullets or numbers?

Is the order of the points important? If yes, use numbers. If no, use bullets. Easy!

Capitalisation

Capital letters are used for proper nouns, for abbreviated acronyms, and for any specific words we use to describe our products - Codebots, Model Driven SaaS, and the Diagram Editor.

Headline style

For headings, we use sentence case (not to be confused with sentence style). Sentence case means making only the first letter in a heading a capital letter. Proper nouns are capitalised, and certain other words (like product names).

In some cases, we will capitalise a title, such as the headline used on the dotcom homepage - however this is a case by case scenario.

Apostrophe or no apostrophe?

Apostrophes can be hard! So don’t assume that just because you’re about to put an S on the end of a word, it requires one. Apostrophes are only required when: • You have taken letters out (when “you are” becomes “you’re”) • You want to show possession (“Lana’s laptop”).

Dashes

There are basically three types of dashes: em-dash (the width of a capital M: —), en-dash (half the width of an em-dash:­­­ –), and hyphens (the one on your keyboard: -).

Oxford (or serial) Comma

The Oxford or serial comma is used before the ‘and’ in a list, like this: “red, green, and blue”. If you went to school in Australia, you were probably taught that a list looks something like this: “red, green and blue”. The AGSM agrees, unless a serial comma is required for clarity. If you went to school anywhere that teaches non-Australian English, you were probably taught to use an Oxford comma, because it’s clearer. So, if you are writing for Australian audiences, and your meaning can’t be misconstrued, feel free to leave the Oxford comma out. If you think it helps make things clearer, go ahead and use it. You get to choose in this case!