Clear and to the Point

11 August, 2011

Who’s shooting whom?

Filed under: accuracy,communication,editing,writing — monado @ 10:47
Tags: , ,

It’s important in technical documentation to be clear about who does what. It’s also important in news reporting. One of my pet peeves is this kind of headline from the Montreal Gazette:

Headline from Montreal Gazette, 'Bystander among two dead in Montreal police shooting.'

The headline is ambiguous; but this is the first article about the crime, so you can read the first paragraph to find out that the police were the ones who fired carelessly into a public street and killed someone who was merely walking to work.

News article with marked phrases 'Montreal police shooting' and 'Two men were shot by an officer'

In later articles, the phrase “police shooting” will appear again and it will be harder to find out if the crime is shooting of police or by police. This kind of writing should be outlawed!

28 September, 2010

Beware overstuffed sentences

Filed under: editing — monado @ 07:21

If you’re writing to be understood, one of your most powerful techniques is to put one idea into each sentence. Here’s an overstuffed sentence explaining how stalagmites in caves can be used to calculate the ages of the caves and more. The introductory fact is, “Like trees, stalagmite contain seasonal growth lines, which vary in thickness according to the amount of water available.” But then comes this information overload:

The oxygen and carbon isotope ratios locked into the crystalline structure of calcites in each growth line also provide evidence for the prevalent temperature and the proportion of trees versus grasses in the local environment, respectively.

“Respectively” tells the reader, “You sort it out.” Here’s what I’d rather read:

Each growth line represents a year. The isotope ratios in the calcite crystal structure tell us more about that year. Oxygen isotopes (O16:O18) show the temperature. Carbon isotopes (C13:C14) show the proportion of trees to grasses in the local environment.

If you want someone to read and understand, sort out the ideas and make them flow.

10 September, 2010

Beware long interpolations

Filed under: technical communication — monado @ 15:42

Sometimes, writers insert useful but parenthetical information into an otherwise straightforward flow of thought.

[Our company] requires the services of a skilled systems professional, with strong technical writing experience with user manuals and online help in a ZippyWrite* environment, to assist one of our clients on a contract basis.

The problem with that is that the reader must hold in mind the first part of the sentence, process and store the middle, and then splice the first part to the final part. It’s like holding your breath: the longer it takes, the worse it feels. So let’s do the work for the reader and give them two complete thoughts:

[Our company] requires the services of a skilled systems professional on a contract basis to assist one of our clients. We are looking for someone who has strong technical-writing experience with user manuals and online help in a ZippyWrite* environment.

We can even remove some of the vaguer terms and replace them with specifics:

[Our company] requires a skilled technical writer on contract, to assist one of our clients. The writer must have strong experience writing both user manuals and online help in a ZippyWrite* environment.

*Name obfuscated to avoid mentioning a real product

9 September, 2010

Beware too many words

Filed under: editing,plain language,technical communication,writing — monado @ 13:25

Here’s a sentence from a job ad:

The successful candidate must be available to commence the duties of this position as soon as the selection process has been made.

I prefer the usual form:

You must be able to start immediately.

8 September, 2010

Beware sonic writing

Filed under: editing,writing — monado @ 17:58

I just came upon this: “The instructor is NOT required to have course wear.”

I think that the writer meant, “We supply the instructor with courseware.”


10 March, 2010

Make Twitter work for you

Filed under: technical communication,technology,Twitter,writing — monado @ 17:15
Tags: , ,

Anne Gentle is our guide to how to use Twitter and other social media for the necessary marketing of a freelancer and, more intriguingly, for technical documentation. Read “Focus on Twitter for Technical Documentation.”

Next Page »

Blog at