Archive for the ‘Styles’ Category


Google Developer Documentation Style Guide made public

September 8, 2017

Google recently made public its style guide for developer documentation. You can find it here:

At a quick glance, it offers up some clear, plain language information on how to treat various punctuation and wording. I particularly liked their overall recommendations regarding date and time formatting: Why? Because formatting that looks like this — 1/6/2017 — can be misinterpreted by readers as either January 6 or June 1, depending on where in the world you live or were educated.

[Links last checked September 2017]


Naming names: part 2

April 15, 2016

There’s a reason you should use quite different first and middle names for your children AND use names that are different from their parents/grandparents… Your descendants ancestors searching records for genealogical information will thank you for it!

Below is an image of the information I found in some South Australian records — I’ve confirmed the names and years of birth based on the parents’ names, but I can’t confirm dates of marriage/death etc. as there are SO many names the same, or variations of the same names! What a mess!


Note the names of the parents… and then the names of the children. Note also how there are male and female variations of the same name (Johann/Johanna/Johanne and August/August), and repetitions (brothers: Johann Freidrich and Johann Friedrich William; father and son: Johann Gottlieb; mother and daughters: Johanna Caroline, Johanne Caroline, Caroline). Some of the repetitive names may have been the result of infant deaths, but it’s very hard to confirm this with so many names the same.

It’s possible that ‘Anna’ was christened ‘Johanna’ based on the pattern here. I think Maria and Hermann got off lightly.

See also:

[Links last checked April 2016]


Don’t rely on spellcheck

November 5, 2015

I’ve said it before, and I’ll say it again — a spellchecker won’t save you if the word you’ve typed incorrectly is a real word in its own right.


See also:

[Links last checked November 2015]



Plain language writing

October 29, 2015

Last week I presented a session titled Plain language writing: Tips for delivering complex messages to a general audience at the inaugural Perth Business Writers’ Conference.

The full deck of slides (but not the exercises) and the plain language alternatives handout are available on my website:

[Link last checked October 2015]


Starting a sentence with a conjunction

October 1, 2015

Based on a Writing Tip I wrote for my work colleagues.


One of the authors asked me about starting a sentence with Because:

I was curious about a change you made. The original paragraph started with “As the trunkline fluids….” and you changed it to “Because the trunkline fluids……”

As Because the trunkline fluids will spread and weather rapidly due to wind and weather, containing/booming the fluids to the required thickness to start and maintain a controlled burn is not…

I was under the impression that you shouldn’t begin a sentence with “Because.”

Can you shed any light on this for me?

Great question!

You can start a sentence with a conjunction – and, but, because etc. Typically, that ‘rule’ about not starting with a conjunction is a hangover from early school days and teachers who had it inculcated into them in their school days, possibly back to when Latin was the lingua franca.

I changed it to because because as has so many possible meanings (24, according to [Australian] Macquarie Dictionary). Because only has four meanings in Macquarie, two of which are colloquial and irrelevant to the context, and the other two are basically the same – ‘for the reason that’.

As far as business report writing goes, starting a sentence with And or But may be too casual. However, in our reports we start sentences with However (a good substitute for But), Although, While, Since, Therefore, etc. all the time – I put Because in the same category. I always check sentences starting with As, because that word has so many possible meanings, and will substitute something more appropriate to the context if necessary.

The Australian Style Manual (which, along with Macquarie, is one of our authorities) says this (p72-73):

‘Because’ and other subordinators to start a sentence

The idea that words like because, although, since and while cannot be used at the start of a sentence seems to arise out of a mistaken assumption that, because conjunctions join phrases or clauses together, they must have words on either side of them. This does not happen at the start of a sentence, hence this odd prescription. The reality is that a subordinating conjunction goes with the subordinate clause, wherever it is placed:

We notified the secretary because he is the person responsible.

Because he is responsible, we notified the secretary.

These perfectly grammatical sentences show the subordinating conjunction at two different points in the sentence, prefacing the explanatory clause (‘he is the person responsible’). Explanatory and other subordinate clauses (such as those with if and when) can certainly be used at the front of a sentence, and the conjunction will then be the first word.

Other discussions on this:


[Links last checked October 2015]


Mapping changing language

July 30, 2015

Based on a Writing Tip I wrote for my team…


English is a changing language. Some changes take centuries; others are much quicker. Changes that apply in Australia may not apply in the UK or US, and vice versa.

This Writing Tip discusses some language changes and shows how computer algorithms can plot these graphically. My focus is on the paired words that start as separate words, morph into a hyphenated form, and then become a single word.

I’ll start with an easy one that changed very quickly: database. At one point in the 1960s and 70s it was two separate words (‘data base’), then briefly went through a hyphenated phase (‘data-base’), before settling down and becoming the single word we’re all familiar with (‘database’).


Likewise, ‘email’ – it started as ‘e mail’, became ‘e-mail’ for quite a while, and is now accepted by most style guides as the single word, ‘email’, though ‘e-mail’ is still hanging on in usage.


Many words are at different stages of morphing into a single word – some will never get there, others may remain hyphenated for a long time (decades, centuries), while others leap into single word status very easily. Who decides when a word pair becomes one? Lexicographers (the people who write dictionaries), who follow usage patterns when deciding whether to hyphenate, join, or leave separate a word pair. But lexicographers can’t keep up with usage patterns that change very quickly, so dictionaries are just one guide as to how to deal with a word pair.

More recently, computer algorithms (such as that used by Google Books Ngram Viewer: are plotting usage across centuries of writing (since 1800). However, as far as I can tell, there seems to be no way for casual users of the Ngrams to separate the language of books written in American English from those written in British English (and forget about Australian English – I doubt many books in the Google Books database use Australian English). This means that the results, while fascinating to some, don’t take the place of dictionaries in the ‘home’ language. Algorithms of usage patterns also don’t take the place of style guides put out by professional associations and societies (see this article on whether a honey bee should be a ‘honeybee’ or not:

I used Google Books Ngram Viewer to track down a few words that we use, which have several variations, to see when usage changed. My search criteria for each was separate words, hyphenated form, and joined form. What these graphs don’t show is whether the word is used as a noun, adjective, verb, or something else – context can dictate how you deal with a word pair (e.g. ‘to start up’ something [two words, verb] is quite different to ‘start-up activities’ [adjectival phrase]). Update: I’ve since found out you can specify which part of speech — the ‘Part-of-speech’ information on this page:

If you’re interested in language, try the Ngram Viewer with your own words to see when words came into usage (just enter one word), how they changed (enter variations of the word), etc.












This last one compares ‘color’ and ‘colour’ (click on it to view it full size), but doesn’t separate out the British or American English usages/instances. Surprisingly, ‘colour’ was most common until about 1890 when ‘color’ came into prominence. Was this a reflection of language usage, or that the Google Books project had more British English books published in the 1800s scanned than American English ones? And vice versa after the 1890s?


For fun, I entered a single four-letter word and came up with this graph, which clearly shows that the word was used in printed books until the 1820s and then did not appear again in books until the late 1950s! Those Victorians had a lot of influence…



And I entered another word (‘gay’) that has changed meaning over the past 100 years, dropping out of usage as that change occurred (from the 1940s to 1980s), then picking up its current usage from the early 1980s:


I also checked the stats for ‘awesome’, which show a big swing upwards from the 1960s onwards:


And in the same vein, I checked ‘groovy’, which surprisingly was used as far back as the 1840s, but had its heyday in the 1960s and 70s, with a resurgence in the late 1990s/early 2000s:


Fascinating stuff! I could play all day…

See also:

[Links last checked Aug 2015]


Dealing with ‘Properties of Materials’

February 12, 2015

A few months ago ‘S’ asked about the heading ‘Properties of Materials’ and wondered if it should be ‘Material Properties’ or ‘Materials Properties’ instead. Her colleague had said both alternatives were incorrect (I agree), and should be either ‘Material Properties’ OR ‘Material’s Properties’ (if only one material; ‘Materials’ Properties’ if more than one). She also wondered about a related table caption: ‘Carbon Steel and Cladding Material Properties’.

My response

In my opinion, these heading variations sound awkward, so the original ‘Properties of Materials’ is likely the best (I couldn’t find any dictionary or style guide advice to support this opinion, just my gut feeling about the original phrase’s ‘understandability’). Usually, I’d avoid ‘XXX of YYY’ and change it to ‘YYY’s XXX’, but for S’s example I would keep the ‘XXX of YYY’ construction as it’s much clearer to the reader.

Another possibility is to avoid ‘Materials’ altogether and just use ‘Properties’, or be specific as to the type of properties (see the mini table of contents on this Wikipedia page for examples:, or use a synonym (however, don’t change it to ‘Materials’ Characteristics’ otherwise you’ll have a whole slew of sibilants your reader has to deal with).

As far as the table caption goes, consider deleting ‘Material’ from it; ‘Material’ is already implied based on the heading and the preceding text.

Bottom line: Ultimately you are writing for whomever is reading the document, so your aim is to keep your words as plain, simple, and—most importantly—as unambiguous as possible. Don’t force the reader into a situation where they have to stop reading to figure out the meaning.

(By the way, a Google search gave me 17 million hits for ‘Properties of Materials’ and only 300,000 for ‘Material Properties’, in case that matters.)

[Link last checked February 2015]