decorating before building

Imagine you are building a house.

You’ve contacted a whole lot of suppliers, to bring you all the necessary building resources. And today, they’re all going to bring them so that you can actually start the building.

The bricklayer arrives with 5000 bricks – each one individually plastered, and painted, on one side. “Well, since I knew what colour you wanted for the rooms, I figured I’d do the painting first. Now, you just have to put the bricks together, and you’re done! Isn’t that convenient?”

The carpet guy has brought carpet – already cut into a floor shape, even though you haven’t fully settled on the house’s layout yet. “Oh, it was easy!” he enthuses. “I just looked up a list of the ten most common floorplans, and combined them, then cut the carpet to match! Helpful, right?”

The electrician doesn’t even talk to you. He’s too busy setting up beautiful side-table lamps – on the ground, since you don’t yet have any side-tables… or, in fact, any floor.

There are a lot of documents out there that get made by multiple people. Some will be of the everyone-does-their-own-chapter variety; some will just go from the writer, to the editor, to the designer. But almost all of them will land on my desk – and make me feel like the builder above.

You see, every person who works on a document will try to make it pretty. They’ll fix all the fonts, change all the spacing, and make the headings sparkly and blue.

…and then, I put their chapter together with a different one. Now we have one chapter in Times New Roman and one in Ariel, all the spacing is completely screwed up, and the headings are now programmed to be sparkly and blue and scrolling across the page and bright red, and, basically, the thing’s a mess.

I am experienced at dealing with documents like this. But many people aren’t. And if one of those not-so-experienced people is given the task of sorting out your messy collaborative document, they will hate you for the rest of time.

If you are working on a collaborative document, your job is simple: you are supplying the basics. You need to write things down, put them in a logical order, and give them to the person in charge.


You might feel like you’re saving time by making the document look pretty – but you’re actually ensuring that the editor will need to waste a couple of hours removing all your design efforts before they can actually start putting everything together.

Don’t paint bricks before laying them. It never really helps.


Just a brief note…

25×10mm is a straight line. A straight line made up of 25 segments, each 10mm long.

25mm×10mm is a 2-dimensional space. It is 25mm long, and 10mm wide (or vice versa).

250mm^2 is an area that corresponds to a 2-dimensional space that is 25mm long and 10mm wide. Or to a space that is 125mm long and 2mm wide.

These three dimensions? ARE NOT THE SAME THING.

If you’re writing a technical document, please check whether you’ve accidentally left out or put in a “mm” where you shouldn’t have. There’s a real difference between the three options.

repeating yourself

I am currently editing a rather long document, giving technical requirements for installing a whole bunch of stuff. Lots of technical requirements.

The thing is, the author clearly hadn’t planned out what he was going to say beforehand. He just sat down, started writing, and wrote down requirements as they occurred to him. Which means you get something like this:

1) The fridge must be on the right-hand-side of the kitchen, with enough room to open the door fully.
2) The sink must be installed by a qualified plumber.
3) If the stove runs on gas, it must be checked for gas leaks once a year.
4) The fridge must be on the right-hand-side of the kitchen, with enough room to open the door fully.
5) There must be space provided for a microwave.
6) If there is a gas leak more than once, the stove must be changed to run on electricity.
7) The fridge must be on the right-hand-side of the kitchen, with enough room to open the door fully.

…only the document I’m dealing with does this for nearly 60 pages.

It’s almost impossible to find the information that’s needed, requirements get repeated over and over again, and I am frankly amazed that the writer managed not to contradict himself – because it’s so easy, when writing like this, to say that Mars needs three separate space colonies, and then, a few pages later, that Mars needs five space colonies, and not even notice that you’ve done it wrong.

Look at all the things you’re mentioning, and find some common topics. Then, put each item in the same place as all the other items on that topic. That way, you can make sure you haven’t repeated or contradicted yourself, and you’ll also make your document much easier to navigate.

being wordy

I recently edited a sentence which went something like this:

The Mission Control Team is responsible for facilitating the development and advocacy of interstellar missions.

In the end, it became this:

The Mission Control Team develops and advocates for interstellar missions.

Because, really, “responsible for facilitating” is just so much noise. It’s unnecessary – all it does is make the sentence far too wordy.

Similarly, the students have not been “given the opportunity to demonstrate their learning of grammatical concepts”; they have simply “learned about grammar”.

Say what you want in simple language. Don’t use more words than you need to.

this is (a bad) example

Let’s talk about brackets.

To start with, a clarification.

To American readers, these
( )
are parentheses. And these
[ ]
are brackets.

To British and Australasian readers, these
( )
are brackets. And these
[ ]
are square brackets.

I am Australian; I’m talking about the round ones.

Brackets are something that are commonly done incorrectly.

Example 1

The capture of Alpha Centauri must be swift, efficient, (and where possible) bloodless.

Example 2

There were five lions in the enclosure. (One of them was staring at him). Mark decided to take a photo.

Example 3

The bowl of fruit includes two apples, five bananas, and a tomato (yes, tomatoes are really fruit.)

These are all incorrect. Why? Because the bracket doesn’t contain things it should – or does contain things it shouldn’t.

Brackets should be used for “asides”. They are for those bits of text that are interesting, but not really part of the main text. And, because they’re not a part of the main text, it should be possible to remove them from the main text, without any sign that they were there.

If the brackets are removed from the above examples, this is what happens:

The capture of Alpha Centauri must be swift, efficient, bloodless.

The “and” has disappeared. Without it, the sentence doesn’t work properly.

There were five lions in the enclosure. . Mark decided to take a photo.

Suddenly, there is a full stop sitting in the middle of the paragraph, for no reason at all.

The bowl of fruit includes two apples, five bananas, and a tomato

This sentence, on the other hand, has completely lost its full stop.

When using brackets (otherwise known as parentheses), it is important to make sure that you could remove them and everything inside them from the text, without anything suddenly being incorrect.

Check your brackets carefully.

it’s vs its

It is astonishingly easy to get some words confused. This is one of the worst.

Now, if you’re just wanting to know, very quickly, exactly which is which, then look no further:

it’s: “it is” (as in “it’s two months until my voyage to Mars”)
its: “something that belongs to it” (as in “the dog was very unhappy until I found its chew toy, and now everything’s okay”)

But if you’re wondering why “its” looks the way it does, stick around while I get word-geeky…

At first glance, “its” looks horribly wrong. After all, “Kathy’s bag”, “my father’s last wishes”, and “the space-port’s tractor beam” all have apostrophes; why wouldn’t “its”?

It’s all a matter of nouns and pronouns.

Nouns are the names of objects: bicycle, dog, father, Kathy, Poland, Wednesday, autumn, fear, and so on. For any of these, if they own something, then they also get an apostrophe to go with it.

Hence we have “the dog’s paw”, “Poland’s ruler”, and “Wednesday’s timetable”. All the owners are nouns; all of them use apostrophes.

Pronouns, on the other hand, are these:
– me
– you
– he
– she
– us
– them
– it
…and so on. They’re words for talking about something without ever actually naming it.

All of the pronouns can own things – but without apostrophes. Like so:
– my bike
– your wedding
– his plans for world domination
– her sense of humour
– our zombie legions
– their fault
– its eyes

None of them have apostrophes. Not even “its”.

As a rule: nouns use apostrophes; pronouns don’t. (The exception to this rule is “one” as in “one’s sense of duty”, but that’s a whole other story.)

looooooong sentences…

I recently edited a job description, for someone advertising for a new employee.

The first line looked something like this:

The Communications Manager will:
a) Provide communications expertise to the Director, Public Manager, and Technical Team, in the fields of Technical Communications and Communications Engineering, in a variety of areas, such as writing reports, providing advice to stakeholders, leading the Communications Team, compiling research into a usable format, and advising the Director on subjects related to communications.

That was all ONE SENTENCE.

I could see what he was going for: he wanted to have one sentence per dot point. Unfortunately, he was so committed to having one sentence per dot point that every sentence had morphed into this huge behemoth full of commas, and he hadn’t even noticed.

If your sentence takes up more than two lines on a page, it is almost certainly too long. Break it down into smaller points, so that it’s easier for your readers to keep up.


Get every new post delivered to your Inbox.