That versus which

Based on a writing tip I wrote recently for my work colleagues…

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

Bottom line:

• Use ‘that’ if the phrase is integral to the meaning of the sentence (i.e. a ‘restrictive’ or ‘essential’ clause).
• Use ‘which’ if the sentence can stand alone without the phrase (i.e. ‘non-restrictive’ or ‘non-essential’ clause); a ‘which’ clause typically expands on or enhances the information already given.
• ‘Which’ typically follows a comma, whereas ‘that’ rarely does.
• A good test for when to use ‘that’ or ‘which’ is to remove the clause—if the sentence still makes sense, use ‘which’; if it doesn’t, use ‘that’. 

One area where I make a lot of corrections when editing a document is the use of ‘that’ or ‘which’. There are hundreds of web pages devoted to discussing the differences, some very technical – I’ve listed a few below.

Your use of ‘that’ or ‘which’ depends on whether your clause is restrictive or not.

Examples of non-restrictive clauses (i.e. they could be removed without changing the meaning of the sentence) where you would use ‘which’ are shown in red:

• A subset of the Emergency Response Plan is the Marine Oil Pollution Plan, which describes the [company's] response to an oil spill.
• Maps and detailed information have been compiled for [location], which detail the beaches, vehicle access tracks, habitats, vegetation communities, mangroves, and other sensitive areas.
• The largest vessels of the fleet, which represent the greatest potential spill volumes, always operate with support vessels nearby.
• All bores, which include production, exploration, and purpose-drilled monitoring bores, are to be sealed or capped appropriately to prevent ingress of fauna.

Examples of restrictive clauses (i.e. the clause is integral to the sentence’s meaning) where you would use ‘that’ are shown in red:

• Known active warrens occupied by [animal] are to be trapped by [company/government department] within one week prior to clearing, so as to remove individuals that occupy the warren and relocate them elsewhere (under licence) as agreed between [company] and [government department]. (NOTE: This one is restrictive as you’re only referring to individuals that occupy the warren, not all individuals.)
• For sites that are cleared in progressive stages, fauna searches should be undertaken at each stage of clearance. (NOTE: This one is restrictive as you’re only referring to specific types of sites, not all sites.)
• Techniques that wash oiled sand into the lower intertidal and subtidal zones should be avoided. (NOTE: This one is restrictive as you’re only referring to specific types of techniques, not all techniques.)

[And no, I won't comment on the use of passive voice in these examples...]

See also:

• http://grammar.quickanddirtytips.com/which-versus-that.aspx
• http://grammar.quickanddirtytips.com/which-versus-that-advanced.aspx
• http://www.dailywritingtips.com/that-vs-which/
• http://www.grammarbook.com/grammar/whoVwhVt.asp
• http://www.worldwidewords.org/articles/which.htm

[Links last checked May 2013]

Hard-hitting message in one simple poster

I spotted this poster at a rest area on the drive north on Interstate 35 from Texas Hill Country back to Dallas. I liked its simple message, so effectively communicated in both words and pictures. It packed a punch. It’s such a shame that the organization that commissioned/created  this poster probably can’t afford to put it on those HUGE billboards that pepper US highways, where the message needs to be communicated the most.

(Click the photo to view it larger.)

Wishy-washy words like ‘it’ and ‘this’

Based on a writing tip sent to my work colleagues. Some identifying content removed and replaced with [...]. My colleagues and I work in the oil and gas industry, so the information about the potential to cost lives is very real for us.

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

In this writing tip, I look at wishy-washy words like ‘it’ and ‘this’, with some ‘we’, ‘our’, and ‘they’ rounding out the list of words that can take on more than one meaning, depending on context.

Bottom line:

• Be specific. Be clear. Be unambiguous. If your sentence (or preceding sentence) refers to more than one subject or object, avoid ‘it’, ‘this’ etc. otherwise your reader has to stop to figure out what ‘it’ etc. refers to. If necessary, use the word/phrase a second time, reword the sentence, or split the sentence in two to avoid ambiguity and misinterpretation.
• Hesitations and misinterpretations incur productivity losses and may cost lives.

Let’s look at some examples that have more than one possibility for ‘it’ etc. I’ve indicated the troublesome wishy-washy word in bold in the first column and have included the surrounding sentences to place the ‘it’ in context. In all cases, replacing ‘it’ etc. with the name of the thing being referred to would fix each sentence; some rewording may be required.

Example	Comment
Before formally entering the finding into the tracking tool, the finding shall be communicated and agreed with the action party. If no agreement is reached, or if no communication is received from the action party, it shall be escalated to the action party’s manager.	What is ‘it’ in this context? The finding? The lack of agreement? The lack of action from the action party? Something else?
The [...] Risk Management Process describes key roles and responsibilities and establishes measurement and verification activities designed to monitor [...] Risk Management and to promote a process of continual improvement. This includes quarterly reporting of leading and lagging indicators, annual review of process effectiveness, and periodic corporate auditing.	What is ‘this’ in this context? The Risk Management Process? Monitoring? Promoting? Continual improvement?
Approval is requested through this Plan to potentially use treated water from the WWTP on site for non-potable construction purposes (e.g. dust suppression, compaction, washdown). This is in line with the waste management hierarchy and will result in a significant reduction in freshwater use on[...]. This will occur when the capacity of the WWTP to treat wastewater to the required specifications is achieved.	What is ‘this’ in these contexts? Approval? Use of  treated water? While the first ‘this’ likely refers to the use of treated water, the second ‘this’ is very hard to figure out.
If the Contractor ‘adds value’ to a Company dataset, it shall be submitted to the Company Representative with an updated metadata record.	What is ‘it’ in this context? The revised dataset? The added value part only? Specific metadata records? The Contractor??
However, the Core Project Team will work closely with this other project during Phase 3 to ensure we support early engagement with selected third-party Contractors to seek endorsement of our preferred alternatives for waste disposition equipment.	Who is ‘we’ and ‘our’ in this context? Core Project team? [company name]? Some other entity? (As an aside, avoid ‘we’, ‘our’ in all formal/business documentation – instead, use the entity’s formal name)
Note that when Reference Site [...] was included in analyses, it showed this site was significantly different to all other sites, both during the [...] Baseline Program and the [...] Survey.	What is ‘it’ in this context? The analyses? The results? Something else?
Should monitoring indicate that grazing is significantly impeding rehabilitation recovery, then the perimeter of rehabilitation areas may be fenced to exclude grazing fauna. If fenced, it will be maintained until the vegetation is sufficiently established to withstand grazing pressure.	What is ‘it’ in this context? Rehabilitation areas? Perimeter fencing? Grazing?

Other examples where the meaning is unclear, though these examples don’t use ‘it’ etc.:

Example	Comment
Findings shall be discussed prior to being raised with the person who facilitated the verification activity.	Discussed with whom?
Additionally, the collection of all deck water for storage or treatment prior to discharge (e.g. through an oily water separator) is impracticable as this would require significant modifications in port to the vessels involved in the installation activities.	Are the modifications to be made to the vessels or the port? This example shows how misinterpretation can occur if you separate the thing (the vessels) being acted on (modified) and where those modifications are to take place (the port). Rewording this sentence would remove this ambiguity – for example: ‘… as this would require significant modifications to the installation vessels; such modifications would be carried out in port.’ OR : ‘… as this would require significant in-port modifications to the vessels involved in the installation activities.’

Finally, don’t eliminate all ‘it’ etc. words from your writing – they definitely have a place, but only where they reference a SINGLE thing and there’s no ambiguity as to what that thing is. (You may notice I used ‘they’ in the previous sentence – in this sentence, ‘they’ refers to ‘it’ etc. words, and can’t refer to anything else, so it’s perfectly acceptable to use.)

*********
And to add some humor, there’s this:

Day, night, anytime: Time and date formats

Based on a writing tip I recently sent out to my (Australian) work colleagues.

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

In this week’s writing tip I deal with times and dates and how to write them so that their meaning is clear and unambiguous to all readers. I’ve taken most of this information from our style authority, the most recent Australian Style Manual: For authors, editors and printers (6th ed, John Wiley & Sons, 2002)

Bottom line:

• 24-hour time: four numerals only, no punctuation, no spaces (e.g. 1712)
• 12-hour time: include am or pm, separate hours and minutes with a full stop (e.g. 9.30 am), use noon and midnight instead of the ambiguous 12 am or 12 pm
• Avoid bi as a time frequency – use other words to say what you mean
• Write dates in this order: day (numeral) month (word) year (numeral), with no punctuation e.g. 4 September 2012

Time formats

The Style Manual (p172-173) has:

• 24-hour time: examples: 1700, 2318 etc. (‘Four digits are always used, the first two showing the hours and the last two the minutes. Neither punctuation nor space is inserted. Where more precise times that include decimal fractions of seconds are being expressed, colons can be used as the separator [as recommended by ISO 8601:2000]. For example: 23:59:17.’)
• 12-hour time: examples: 5 am, 9.00 am, 7 pm, 10.15 pm etc. (‘…present am and pm in lower case … The use of full stops between these abbreviated words [a.m. and p.m.] is declining and, because they are always preceded by a numeral, they can be treated like other symbols associated with numerals, which are unpunctuated. A full stop should be used to separate the hours from the minutes. Two zeros may be used to indicate even hours but are not essential [i.e. 5 am or 5.00 am are both correct].’
• The special case of noon and midnight: ‘Under the twelve-hour system, practice differs on the presentation of noon and midnight. Where confusion could be caused by using 12 am or 12 pm, it is preferable to use the terms noon and midnight. Thereafter, 12.01 pm refers to the beginning of the afternoon, and 12.01 am to the early morning.’

Date formats

The Style Manual (p170-171) has:

‘… dates are best presented using numerals for the day and year but with the name of the month … in full.’ Thus: 4 September 2012 (‘This structure is unambiguous, requires no punctuation, and progresses logically from day to month to year [...] and requires fewer keystrokes.’)

Unacceptable date formats include:

• the 4th of September, 2012
• 4th September, 2012
• September 4th, 2012
• September 4, 2012
• 4 Sep 12 (unless space is very limited, such as in a table cell)
• 4/9/2012 (this format is the LEAST ACCEPTABLE as it will be read by US readers as 9 April 2012. The Style Manual [p171] says: ‘All-numeral forms of dates can mislead because international practice varies, so ISO 8601:2000 should be followed in documents for wide distribution.’ [Note: ISO 8601:2000 specifies writing all-numeral dates in YYYYMMDD format, so 4 September 2012 would be 20120904; see also: http://cybertext.wordpress.com/2008/01/28/date-and-time-formats/]),

Words related to time

The special case of ‘bi’ words (Style Manual, p173): ‘Most prefixes that can be attached to an expression of time to indicate frequency are unambiguous—for example, tercentenary and triennial. But the prefix ‘bi’ poses problems, because it means both ‘two’ and ‘twice a …’; so bimonthly can mean either ‘every two months’ or ‘twice a month’. It is better to use more specific alternatives in place of this prefix, such as ‘twice weekly’ or ‘fortnightly’, or ‘twice monthly’ or ‘every two months’. In contrast, biannual and biennial each have one meaning only: respectively, ‘twice a year’ and ‘every two years’. Nevertheless they are often misunderstood, and so should only be used in contexts where their meaning can be made clear.’

And just to keep you on your toes, other time-related words are treated in various—sometimes conflicting—ways in the Macquarie Dictionary. For example:

• afternoon and daytime (no hyphens/spaces) compared to night-time (hyphenated)
• night shift and day shift (both separated by a space)
• midnight, midday, and midafternoon (no hyphens/spaces)

[Link last checked November 2012]

Learned vs learnt

Based on a writing tip I wrote for my work colleagues…

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

This week’s writing tip is the result of a question that Michael asked – is it ‘lessons learned’ or ‘lessons learnt’? Good question, Michael!

Bottom line:

• Use your main dictionary authority for guidance (Macquarie Dictionary is our authority, and they only use ‘learnt’ as the past tense of the verb ‘learn’)
• Know your audience – are they predominantly American (‘learned’) or Australian (‘learnt’)?
• ‘Lessons learnt’ is the correct form for documents that will predominantly be read by Australian readers.

The issue of using ‘t’ or ‘ed’ as the past tense ending of certain verbs is a curly one, and tends to divide according to whether you were taught British/Australian (‘t) or US (‘ed’) English. Some examples of these irregular verb form endings include ‘burned’/‘burnt’, ‘spelled’/’spelt’, ‘dreamed’/’dreamt’, ‘spilled’/’spilt’, and the one that we use most often in our documents – ‘learned’/’learnt’.

Macquarie Dictionary has this to say about ‘learnt’ and ‘learned’:

‘learnt’: verb a past tense and past participle of learn

‘learned’:

adjective 1. having much knowledge gained by study; scholarly: a group of learned scholars.

2. of or showing learning.

3. (applied as a term of courtesy to a member of the legal profession): my learned friend.

Note: Macquarie Dictionary has NO definition for ‘learned’ as a verb, irregular or otherwise.

So, for documents that will predominantly be read by Australian readers, ‘lessons learnt’ is the correct form.

See also:

• The Oxford English Dictionary states that ‘learned’ is the past and past participle verb tense of ‘learn’, whereas ‘learnt’ is the same but ‘chiefly British’ (http://oxforddictionaries.com/definition/american_english/learn)
• Grammar Girl’s articles:
  • ‘Irregular verbs’ (see the section on ‘burned’ vs ‘burnt’): http://grammar.quickanddirtytips.com/irregular-verbs.aspx
  • Dreamed vs dreamt: http://grammar.quickanddirtytips.com/grammar-comments.aspx
  • ‘Why are British and American English different?’: http://grammar.quickanddirtytips.com/british-american-english-differences.aspx
• List of (600+) English irregular verbs: http://en.wikipedia.org/wiki/List_of_English_irregular_verbs

[Links last checked November 2012]

Tightening your writing

Based on a writing tip I wrote recently for my work colleagues.

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

This Writing Tip focuses on ways you can tighten up your writing by removing words and rearranging words. The examples below are from some documents I’ve edited recently. Note that some of these examples swap a word for its plain language alternative (see Gobbledygook, Jargon, and Plain Language).

Bottom line:

• Watch for the excessive use of ‘of’. You can often remove ‘of’ without affecting the meaning of the sentence – if you see an ‘of’ try reading the sentence without the ‘of’ and if it still makes sense, then delete ‘of’.
• Don’t follow these guidelines blindly. The context is important, and what you’ve written may be correct for your context.

Let’s look at some examples from some documents I’ve reviewed:

Instead of…	Try this…
report on an annual basis	report annually
report on a monthly basis	report monthly
on a regular basis	regularly
the frequency at which	how often
in the event of	if
There were no [xxx] recorded	No [xxx] were recorded
has been OR have been	was OR were (depending on context)
until such time as	until
employ	use
utilise	use
in excess of	more than OR exceed
outside of	outside
comprises of	comprises
is comprised mostly of	mostly comprises
are comprised of	comprise
This section seeks to define	This section defines
When communicating, it is important to select the most appropriate method or way of communicating to achieve your goal or objective.	Select the most appropriate communication method to achieve your goal or objective.
ascertain	check
It is a requirement to wear full PPE…	You must wear full PPE…
carried out in a safe fashion	carried out safely
working in a safe and productive fashion	working safely and productively
is presented/provided/given in Figure x.x	is shown in Figure x.x
The [xxx] Archipelago is an area encompassing 42 islands…	The [xxx] Archipelago encompasses 42 islands…
a spill of 700 m3 of diesel	a 700 m3 diesel spill
summer season	summer
testing of [xxx]	testing [xxx]
methodologies	methods
the majority	most
restricted access of fishing	restricted fishing access
mortality	death
measurements of the noise	noise measurements
from the installation processes themselves	from the installation processes
took into account	considered
on the other hand	whereas
will be managed through	will be managed by
The environmental impacts of the spill are dependent to a large degree on	The environmental impacts of such a spill largely depend on
by way of comparison	compared to
report on and include a summary of	report on and summarise

The first column used 178 words (874 characters, not including spaces), while the second column used 111 words (622 characters, not including spaces). So in addition to making the text more readable and understandable, the alternatives require less typing (and less paper if printed).

See also:

• Tighten up your writing by removing unnecessary words
• A good case for cutting dead words

Gobbledygook, jargon, and plain language

Based on a writing tip I wrote recently for my work colleagues. The industry is oil and gas. And yes, I know that ‘bottom line’ qualifies for Buzzword Bingo ;-)

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

Bottom line:

• Use plain language where possible so the reader doesn’t have to try to figure out what you mean.
• Consider how you would explain the concept to your parents, children, grandparents, those who don’t work in the industry etc. – and then use that language in your writing. Plain, simple, and easily understood.
• Every time someone has to stop and think while reading your document, the organisation incurs a cost – time, lost productivity, rework etc.
• Every misinterpretation could put a life at risk.

Let’s look at some examples from some documents I’ve reviewed:

Phrase as written by the author	My comments
‘Each sub-phase will be reviewed and assured prior to proceeding to the next sub-phase.’	What does ‘assured’ mean in this context? None of the dictionary meanings fit how it’s used in this sentence. Does it mean ‘confirmed’, ‘approved’ or something similar? If so, use one of those words so that the reader isn’t confused. (By the way, the Macquarie Dictionary definitions for ‘assured’ are: 1. [adj] made sure; sure; certain. 2. [adj] bold; confident. 3. [noun] boldly presumptuous. None of these really fits the sentence, though I suspect a variation of the first definition is the closest.)
‘could leverage synergies with’	This one would qualify as a BINGO! in Buzzword Bingo (see links below). Consider using plainer language, e.g. ‘take advantage of’, ‘cooperate with’, ‘combine with’, ‘joint opportunity’ etc.
‘to enable performance characterisation of the…’	More business jargon and another candidate for Buzzword Bingo. What does ‘performance characterisation’ mean? How would you explain this to your parents, for example?
‘does not contain a sufficiently large portion’	While the individual words are in plain language, ‘sufficiently’ and ‘large’ are relative terms. What does ‘sufficiently large’ mean in this context? Larger than what? How ‘sufficient’ does it have to be to be ‘sufficiently large’? Either be specific about the size of the portion (using a value and unit of measure) or reword.

For each example listed above, I had to stop and think, try to figure out (guess!) what the author meant, consult the dictionary, or do all these actions. Each hesitation was a distraction that took my focus away from my objective of reading and understanding the content. Each time I searched the dictionary or thesaurus and tried out alternative words in my head, my focus was off the document and onto something else. Instead of reading a paragraph and knowing straight away what it meant, I was distracted – and sometimes confused. Thus the time I took to read and understand the sentence, paragraph, entire document was compromised. And that’s just me. Multiply that lost time by the number of readers of your documents who don’t understand what you mean and thus have to try to figure it out and now there’s a much bigger issue than just a silly word or two.

Let’s say your document is read by 30 people, and each person ‘loses’ just 10 minutes on that one document trying to understand what you’re saying. That’s a business cost of 300 minutes (5 hours) to the organisation for ONE document—a cost that could have been prevented if you’d spent just an extra minute or two converting gobbledygook and business jargon into plainer language. Multiply that over the thousands of documents produced and read by thousands of employees and contractors per year and now you’re looking at a substantial cost to the organisation.

But potentially there’s an even bigger business cost than lost time, and that’s the cost of misinterpretation. Sure, for many documents misinterpretation of a single word or phrase doesn’t matter too much. But ours is an industry [oil and gas] where lives may be at risk if an instruction is misinterpreted, or if a specification uses an incorrect unit of measure (e.g. inches instead of centimetres, grams instead of milligrams) or doesn’t specify a measure (‘sufficiently large’), or if a comma is in the wrong place thus making a sentence ambiguous and open to misinterpretation.

Loss of life, law suits, government inquiries etc. are all potential costs of misinterpretation.

So, after you write a sentence/paragraph/section/document, read it through before finalising it to make sure that all the words/phrases you use will be understood by your target audience. If in doubt, think about how you’d explain it to someone outside the industry and use those words instead. Or get someone else to read it and alert you to anything they can’t understand or that they hesitate over.

See also:

• Varanus Island Incident Investigation: http://www.parliament.wa.gov.au/WebCMS/WebCMS.nsf/resources/file-varanus-report/$file/varanusinquiry2.pdf (specifically, Chapter 1 which details the documentation – and lack of it – regarding the pipeline, operations, inspections, specifications etc.)
• The comma that cost a million dollars: http://www.nytimes.com/2006/10/25/business/worldbusiness/25comma.html?_r=1
• Legal implications of incorrect wording on a document: http://www.ehow.com/about_6494887_legal-implications-incorrect-wording-document.html
• The costs of poor communication: http://www.solari.net/toward-humanity/2009/10/18/the-costs-of-poor-communication/
• Simple word and phrase alternatives: http://www.plainlanguage.gov/howto/wordsuggestions/simplewords.cfm
• A-Z of alternative words: http://www.plainenglish.co.uk/files/alternative.pdf
• Clear or plain language: http://taitcc.com/blog/?p=134

And for fun:

• http://www.plainenglish.co.uk/examples/gobbledygook-generator.html
• http://www.businessbuzzwordbingo.com/

[Links last checked October 2012]

Me, myself, I

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

********

For those old enough to remember, Joan Armatrading sang about ‘Me, myself, I’ way back in 1980 on an album of the same name (http://www.youtube.com/watch?v=Kavu_vuD2QM). Perhaps she was as confused as many others over whether/when to use ‘me’, ‘myself’, or ‘I’ in a sentence and so decided to use them all!

Bottom line:

• ‘Myself’ is RARELY correct
• Take out the extra people so you’re the only one left and see how the sentence sounds with ‘me’, ‘myself’, or ‘I’

Here are three possibilities for a simple request:

• If you have questions please direct them to Paul or me
• If you have questions please direct them to Paul or myself
• If you have questions please direct them to Paul or I

Now, here are the same possibilities with ‘Paul’ removed:

• If you have questions please direct them to me
• If you have questions please direct them to myself
• If you have questions please direct them to I

Read each one aloud. ‘Myself’ and ‘I’ both sound awkward and/or pretentious. The only correct option is ‘me’. Which means that when you put back ‘Paul’ back into the sentence, you have to use ‘me’. The trick for deciding which option to use is to remove the extra person and then see how the sentence sounds.

Some more:

• Paul and me will write the report OR Me and Paul will write the report.
• Paul and myself will write the report OR Myself and Paul will write the report.
• Paul and I will write the report OR I and Paul will write the report.

Again, take out ‘Paul’ and the ‘and’ and read the sentence without the extra person:

• Me will write the report.
• Myself will write the report.
• I will write the report.

This time the only correct option is ‘I will write the report’ so when you put ‘Paul’ back into the sentence, you have to use ‘I’. NOTE: If you’re using multiple people, you always put yourself last (so, ‘Paul and I will write the report’, NOT ‘I and Paul will write the report’).

The number of people doesn’t change the pronoun that you use – if you use ‘me’ for one person, then you use ‘me’ when you list multiple people; if you use ‘I’ for one person, then you continue to use ‘I’ when there are multiple people.

Grammar Girl deals with this ‘me, myself, I’ issue here: http://grammar.quickanddirtytips.com/me-myself-and-I.aspx

BONUS TIP: You could tighten up the first example by removing ‘please direct them to’ and replacing it with ‘contact’ (i.e. ‘If you have any questions, contact Paul or me’), or tighten it even further for an informal email by removing ‘If you have any questions’ and replacing it with ‘Any questions?’ (i.e. ‘Any questions? Contact Paul or me.’)

*********

[Links last checked October 2012; thanks to Peter C for asking the question!]

Consistency: Pick one. Stick with it.

Bottom line:

• Consistency reduces confusion.
• Always use the official term where it exists.
• Don’t use terminology variations just because you think your document sounds repetitive – better to be repetitive and clear than to offer synonymous terms and confuse your readers!

Your readers will get confused if you aren’t consistent in the terminology you use in your documents. Does phrase A mean the same as phrase B? If the words are similar, but not quite the same, are they different things or the same thing? If your reader has to hesitate to figure it out, invariably that means that you’ve confused them. If the words mean the same thing, then you must use the same term for it throughout the document. And always use your organization’s official version of the term, if one exists.

Let me give you some examples of inconsistent words/phrases from some documents I’ve edited recently:

Example 1: ‘Tenets of Operation’ and ‘Tenets of Operational Excellence’ – same or different?

Example 2: The author used these multiple variations in just three pages: ‘workplace participation’, ‘workplace involvement’, ‘workplace consultation’, and ‘workplace engagement’. I wondered whether the author meant these were different things or just one thing. While these phrases *could* mean different things, in the context of what I read they seemed to refer to the same thing.

Example 3: Variations of these terms: ‘LNG Plant’, ‘Gas Treatment Plant’, ‘process plant’. If they are the same thing, then use the same (official) term throughout the document.

Example 4: ‘Construction Camp’ and ‘Construction Village’ – same or different? Again, use the official term, if it exists.

Example 5: Inconsistency is not just seen in the terms used, but also in how they are written: ‘iHAZID’ and ‘IHAZID’ and ‘HAZID’ – same or different? Should the first ‘i’ be capitalized or not? Is the ‘i’ needed?

Where no official term exists, pick one way to write the term and stick with that throughout the document.

Remember: Consistency reduces confusion.

See also:

• Five ways consistency matters (by Geoff Hart): http://www.intelligentediting.com/consistencymatters.aspx

[Link last checked February 2012]

Error messages that make you feel stupid

Back in 2008 I wrote a post on writing useful error messages (http://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:

• doesn’t tell me what to do
• insults me (that single exclamation mark turns this statement into an insult)
• gives me a single option, which is ‘OK’ and that’s NOT OK (see http://cybertext.wordpress.com/2009/02/20/yes-yes-yes-sorry-ok/)

Here it is:

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]