Archive for November, 2011

h1

Magazines are edited, right?

November 30, 2011

Magazines have editors, right? So presumably magazines get edited. After all, you don’t find too many errors in most professionally produced magazines.

If only they applied the same rigor when editing their web copy or email marketing copy…

Email marketing for magazine -- error

Recieve?

Perhaps they didn’t edit the email marketing piece at all.

h1

The serial or Oxford comma

November 29, 2011

Chris asked me to write something about the serial comma (also known as the Oxford comma, among other names). Thanks for the suggestion, Chris!

Bottom line: Separate the last two items in a list with a comma if they could be misinterpreted as being a single item.

A serial comma is the final comma in a run-on list of items; it goes before the ‘and’. (A run-on list is contained within the sentence – it’s not a bulleted list.)

In this phrase, the serial comma is the one immediately after ‘selecting’:

‘…identifying, screening, qualifying, selecting, and integrating the appropriate new technologies to be used in the project’.

Whether you use a serial comma in your writing or not mostly depends on where you went to school. If you went to school in the US, there’s a very good chance that you always use it. However, if you went to school in Australia or Great Britain, you may not use it at all, or only sometimes.

Various style guides have differing rules for its use, so it can all get a little confusing. The Australian Style Manual says this about commas in run-on lists:

‘Commas are used to separate items in a simple series or list within a sentence (e.g. The details required are name, date of birth, address and telephone number.) Sometimes a comma is needed between the last two items to ensure clarity (e.g. They should seek the support of landholders, philanthropists, government, and community and industry groups.)’

Despite being raised in the Australian education system, I tend to add a serial comma after the second last item in most run-on lists to avoid any possibility of ambiguity.

Let’s look at a simple example:

Her favourite pies were lemon meringue, mulberry, apple and pecan.

Without the serial comma, ‘apple and pecan’ could be interpreted as a pie containing both apples and pecans. If the writer meant that apple and pecan were two different types of pie, then they should have added a comma after ‘apple’ to remove any possibility that ‘apple and pecan’ could be interpreted as the one pie:

Her favourite pies were lemon meringue, mulberry, apple, and pecan.

That single comma after ‘apple’ removes all ambiguity and makes it clear that she likes four different types of pie, not three.

Other resources:

[Links last checked November 2011; based on a Writing Tip I wrote for my work colleagues]

h1

Word: Page size not listed

November 25, 2011

Here’s an interesting problem I faced the other day. I needed to insert a section break for an A3 page into a Word document. Everything went fine until I tried to select A3 as the paper size for that section — A3 wasn’t listed! It had been listed for earlier documents, so I was surprised that it wasn’t listed for the document I was working on.

And then I remembered printer drivers. Different drivers have different print capabilities. For example, my office printer cannot take A3 paper in any slot, so it’s unlikely to list A3 as a possible paper option.

I checked the document’s printer settings and found that it was set to the SnagIt printer driver. I changed the printer to Adobe PDF and then checked my available page sizes again — and A3 was there.

I didn’t actually have to print the document — just changing the printer assigned to the document was enough.

h1

Escape? Cancel? What…?

November 24, 2011

I was opening a PowerPoint presentation on my client’s network, using my not super fast VPN connection. I got this cryptic message:

So, I have to press the ESC cancel to stop the presentation from opening. Fair enough, though it could have been written in simpler language (e.g. Press the ESC key to stop opening the document.)

However, that Cancel button just confuses the message. You have two instances of ‘cancel’ in the one message box and it’s not clear as to what the Cancel button does. Does it just cancel the message (I suspect it does) and the document keeps on opening, or does it substitute for the ESC key?

Someone who’s not very familiar with creating a PowerPoint presentation or presenting one, may not be familiar with using ESC to get out of full screen mode once the presentation is open.  Thus they are likely to be really confused by this message.

A better option for the developers/UI text people may be to keep the message, and instead of a Cancel button, adding a ‘close’ icon at the top of the message box, or changing the text on the button to something like Close, though I still think that’s not clear either. Even better would be a wordier message like Close this message. Sure, it’s more text, but there would be no confusion as to what that button does.

h1

Error messages that make you feel stupid

November 18, 2011

Back in 2008 I wrote a post on writing useful error messages (https://cybertext.wordpress.com/2008/04/03/writing-useful-error-messages/), where I stated:

The worst kind of error is one that tells the user nothing and doesn’t help them recover from the error condition.

Also, don’t insult the user or call them stupid… there are many ways developers call users stupid without saying so. For example: “The password is wrong! [OK]”. This sort of error message doesn’t help the user at all, and they feel idiotic for not knowing ‘what the computer wants’. The exclamation mark so beloved by certain developers is like a slap in the face and just adds insult to injury.

Well, I came across one a few days ago that:

Here it is:

Error message with an exclamation point

Thanks for making me feel unworthy

There was no other information on how I could get these obviously special privileges available only to the very few. Even a line about contacting my system administrator might have lessened the impact of this error message.

Removing the exclamation mark would have done a lot to convert this message from a ‘You are too stupid to have privileges’ insult to just a statement of fact. That single punctuation mark in a message such as this has the power to make a person feel like an idiot.

[Links last checked November 2011]

h1

Keep your relatives close!

November 17, 2011

What’s wrong with this sentence?

Physical barriers are provided around the Acme Plant to help prevent damage injury or from dropped or falling objects includes overhead protection and kick plates.

At a quick glance, there are several things wrong with it:

Let’s look at that last one. When you read the sentence as originally written, you could think that ‘overhead protection and kick plates’ are examples of dropped or falling objects because the ‘including…’ phrase comes straight after the ‘dropped…’ phrase.

Someone who does not have English as their native language could easily misinterpret this sentence; native English speakers may compensate and switch the words around in their head to get it right, but there’s no guarantee that will happen. So, how can this sentence be rewritten to make it clear what object the ‘overhead protection and kick plates’ relate to?

There are two objects in this sentence that these ‘including…’ items may relate to – ‘physical barriers (around the Acme Plant)’ and ‘dropped and falling objects’. As the ‘including…’ items are measures to prevent dropped and falling objects, they can’t be examples of dropped and falling objects! That leaves ‘physical barriers’, which fits.

Knowing that ‘overhead protection and kick plates’ relate to ‘physical barriers’, here are some ways of rewording this sentence:

Physical barriers, including overhead protection and kick plates, around the Acme Plant help prevent damage or injury from dropped or falling objects.

or

Physical barriers around the Acme Plant help prevent damage or injury from dropped or falling objects; such barriers include overhead protection and kick plates.

or

Physical barriers around the Acme Plant, such as overhead protection and kick plates, help prevent damage or injury from dropped or falling objects.

Bottom line: Keep your relatives close! Make sure related items stay near each other in a sentence.

See also:

[Links last checked November 2011; based on a Writing Tip I wrote for my work colleagues]

h1

Word: Remove a stubborn watermark

November 16, 2011

Here’s one I solved for a work colleague…

Problem

Word 2007 document with a stubborn ‘DRAFT’ watermark that won’t budge, despite going to the section and trying to remove it the usual way (Page Layout tab > Watermark > Remove Watermark).

Solution

Watermarks have always been stored as part of the header in Word, so:

  1. Turn off track changes.
  2. Double-click inside the section’s header to open it.
  3. Move your cursor over some of the letters in the watermark until it turns into a 4-way arrow.
  4. Click to select the watermark (you’ll see colored selection handles around the watermark text when it’s selected).
  5. Press the Delete key to remove the watermark.
  6. Repeat for all other sections that have a stubborn watermark that you can’t remove.

Update February 2013: If the watermark still won’t delete, trying saving the document as XML — see Amy’s instructions in the Comments (14 Oct 2012), and the following update immediately below.

Update March 2019: See below for the steps for saving as XML and deleting it that way. NOTE: Make a copy of your document and work on the copy. (Always work on a copy to test something you’ve never tried before or aren’t confident doing.)

  1. Open your document in Word.
  2. Save the document as an XML document: File > Save As and choose XML Document from the list of file types.
  3. Close Word. You’ll now have two docs listed in your folder—one with a DOCX file extension, and one with an XML extension.
  4. Open a text editor (e.g. Notepad, EditPlus etc.).
  5. Open the XML document you created in Step 2. Don’t panic when you see all the code!
  6. Place your cursor at the beginning of the file.
  7. Search (Ctrl+F in most cases) for your watermark word(s) surrounded by double quote marks and prefaced by string=. For example: string=”draft” or string=”confidential”.
  8. Delete the watermark word(s) inside the quote marks. There’s no need to delete anything else. You’ll end up with string=”” once you’ve deleted the watermark word(s).
  9. Save the XML document, then close the text editor.
  10. Find the XML document in your folder and open it using Word (NOT a text editor). The watermark should be gone. However, the document is still an XML file.
  11. Save the document as a DOCX file using File > Save As.
  12. Open the DOCX document—the watermark should be gone.
h1

Funny news headline

November 15, 2011

There are SO many pithy comments I could make about this headline, but I’ll refrain!

Lawyers to tackle shark issueOver to you….

h1

Installation confusion

November 11, 2011

I’ve been running some maintenance and upgrades on one of my computers, and came across this after downloading and starting the installation of a driver that HP’s Health Check had recommended:

Confusing installation message

What the...? How do you decipher this message?

I have NO idea what I’m meant to do. The message is confusing, very poorly written (reminiscent of scams/malware, etc.), and appears to be contradictory (the original driver is removed, then you have to go back to the original driver and run its setup.exe to install the new driver??? huh?)

Needless to say, I clicked No and backed out of the installation.

Can anyone interpret what it means? It’s got me totally confused.

I did find one thing with a Google search, but it didn’t tell me if the so-called instructions in this message had to be followed for the installation to happen or not: http://h30434.www3.hp.com/t5/Other-Notebook-PC-questions/Strange-message-when-doing-HP-Health-Check-updates/td-p/751063

[Links last checked November 2011]

h1

Tighten up your writing by removing redundant/unnecessary words

November 10, 2011

Another writing tip that I wrote for my team of authors…

************

Getting rid of redundant or unnecessary words tightens up your writing, thus making it easier for your audience to read and understand your documents.

There is a strong ‘plain language’ movement across many industries and governments (the US enacted Plain Language legislation in 2010) that aims to use language that is clear, concise and correct in all documents, websites, etc. ‘Plain language’ doesn’t mean ‘dumbing down’ the content; rather, it aims to clearly and effectively communicate the message.

So, in the interests of promoting plain language, I’ve listed some sentences I’ve edited recently. On the left are the original sentences/phrases, in the middle are the changes I made, and on the right are my comments. I’ve removed words (represented by ‘…’) that weren’t necessary to make each point. In every example, the word count was reduced and the ‘fluff’ was removed.

Before After Comments
The purpose of the … system is to provide… The … system provides…
  • ‘is to provide’ can be replaced by ‘provides’
  • ‘The purpose of’ can be deleted without changing the meaning
This document has been prepared to outline the … Plan This document outlines the … Plan
  • ‘has been prepared to outline’ can be replaced by ‘outlines’ without changing the meaning
The … Coordinator has responsibility for… The … Coordinator is responsible for…
  • ‘is responsible for’ is more forceful than ‘has responsibility for’ and is easier to read and interpret
…reviews will be conducted on a monthly basis, the frequency is borne out of the reporting requirements. …reviews will be conducted monthly, in line with the reporting requirements.
  • ‘on a monthly basis’ can almost always be replaced by the simpler ‘monthly’
  • ‘the frequency is borne out of’ is hard to interpret and can be replaced by the easier to understand ‘in line with’
The … reporting provides a summative view of performance of the project team. … reporting summarises the project team’s performance.
  • ‘provides a summative view of’ is hard to interpret and can be replaced by the easier to understand ‘summarises’
  • ‘performance of the project team’ can be replaced by the possessive and easier to read ‘project teams’ performance’
The accountability for the maintenance of the information within the register and the administration lies with the … Coordinator. The … Coordinator is accountable for the maintenance and administration of the information within the register.
  • This sentence is clumsy as it separates various things that should go together (maintenance/administration; accountability/lies with)
  • Also, the role that’s accountable is not mentioned until the end
  • By putting the role up front, then stating what that role is responsible for, you get a sentence that’s much easier to read and understand
The [document] provides a summary from all relevant … studies… This [document] summarises all relevant … studies…
  • ‘provides a summary from’ can be replaced by the easier to understand ‘summarises’
Risks are evaluated based on the following: … Risks are evaluated based on: …
  • ‘the following’ can almost always be deleted from the introduction to a bulleted list – if the sentence and list items read just as well without it, delete ‘the following’
A dedicated jetty … is utilised for the loading of LNG… A dedicated jetty … is used for loading LNG…
  • ‘utilise’ (and its variations) can almost always be replaced by the simpler ‘use’
  • ‘the loading of LNG’ can be replaced by ‘loading LNG’ without changing the meaning
…in close proximity to… …close to…
…near…
(or even better, be specific about the distance – e.g. 50 m, 10 m, 300 m, 1 m)
  • ‘proximity’ is synonymous with ‘nearness’ so ‘close proximity’ is redundant. You could use ‘in proximity to’, but it is simpler to say ‘close to’ or ‘near’ – and easier for your readers to understand
  • All these terms are also very fuzzy and not specific – does ‘close proximity/close to/near’ mean 10 m or 500 m? Where possible, be specific as to the distance.
Thunderstorms during the summer months … Summer thunderstorms …
  • Summer is one of four seasons, therefore it covers three months, so ‘during the summer months’ is redundant and can be replaced by ‘summer’
The major systems … are summarised below: The major systems … are:
  • Like ‘the following’, ‘summarised below’ can often be deleted from the introduction to a bulleted list – if the sentence and list items read just as well without it, delete ‘summarised below’
An … injection system assists in the prevention of… An … injection system assists in preventing…
  • ‘the prevention of’ is wordy as are many ‘the … of’ constructions, and can be replaced by the ‘-ing’ version of the word; in this example, ‘preventing’
… is obtained downstream …, whereby it is sent to the … facility … is obtained downstream …, and then sent to the … facility
  • In this sentence, ‘whereby it is’ can be replaced by the simpler ‘and then’
The requirements for … are set forth in the tables below. Table 6-4 and Table 6-5 list the requirements for …
  • ‘are set forth’ can be replaced by ‘list’ (or its variations)
  • ‘below’ should be avoided where possible and replaced with the relevant table/figure/section numbers
  • Reword this sentence to make it easier to understand
…this licence will be further expanded… …this licence will be expanded…
  • ‘further expanded’ is tautological – ‘expanded’ is sufficient
Uninterruptible power supply (UPS) is provided to supply critical instrumentation circuits and other control circuits that could impact safety or continuous operation of processes in the event of a momentary loss of power. If there is a momentary loss of power, the uninterruptible power supply (UPS) supplies critical instrumentation circuits and other control circuits that could impact safety or continuous operation of processes.
  • ‘in the event of’ can almost always be replaced by ‘if’
  • ‘is provided to supply’ can be replaced by ‘supplies’
  • Shift the condition (the ‘if’ statement) to the front of the sentence as the consequence/action doesn’t apply except under that condition
… have been designed to muster >50 personnel … … can cater for >50 people …
  • ‘personnel’ can often be replaced by ‘people’ (though not always)
  • ‘have been designed to’ can be replaced by ‘can’
  • As this sentence was about muster points, the use of a second ‘muster’ was redundant and was replaced with ‘cater for’
In the event that the … is blocked in… If the … is blocked in…
  • ‘in the event that’ can almost always be replaced by ‘if’
The materials of construction for the… The construction materials for the…
  • ‘materials of construction’ is awkward; ‘construction materials’ is easier to read and understand
All detectors are located such that they are readily accessible… All detectors are readily accessible…
  • ‘are located such that they’ was redundant in the context of this sentence and was deleted
… to reduce incident severity and risk of escalation in the event of breach of mechanical integrity. … to reduce incident severity and the risk of escalation if mechanical integrity is breached.
  • ‘in the event of’ can almost always be replaced by ‘if’
  • ‘in the event of breach of mechanical integrity’ was replaced with ‘if mechanical integrity is breached’
Unique, one-of-a-kind… Unique OR one-of-a-kind but NOT both
  • ‘unique, one-of-a-kind’ is tautological – ‘unique’ is sufficient
… in order to… … to …
  • ‘in order to’ can often be replaced by ‘to’ (though not always). If the meaning doesn’t change with ‘in order to’ replaced by ‘to’, then delete it.

See also:

[Links last checked November 2011]