This list is based on work carried out with fellow technical writers Barbara Jones and Diana Muzrimas.
We started out by collecting phrases that we corrected often enough to feel they should go onto a ‘blacklist’. Now I’ve added some more general material on a few topics not directly linked to specific phrases.
Keywords & Topics
able, ability
Avoid
users are able to customise the toolbar
Preferred
users can customise the toolbar
See also capable, capability
actionable
Avoid if possible, unless it means ‘could be the subject of a legal action’
all of the …
Avoid
check that all of the details
Preferred
check that all details …
or
check that the details …
allowed to, not
Avoid
account holders are not allowed to allocate …
Preferred
account holders must not allocate …
and/or
Avoid unless necessary to avoid ambiguity
as a consequence of
Preferred
because
at the end of the day
Omit
at the present time, at this point in time
Use now or just omit
Avoid
at this point in time no decision has been taken
Preferred
no decision has been taken
or (better)
we haven’t decided
aware of
Avoid
site staff are aware of the new communication port settings
Preferred
site staff know the new communication port settings
basically
Omit (almost always)
basis
below
[Rewritten March 2023]
The word below is not an adjective, so if you write ‘the below table’, people may criticise you for being ungrammatical. However, if you change it to ‘the table below’, that will probably appease them.
It’s natural to ask why. The traditional grammarian’s answer is that the ‘below’ in the phrase ‘the table below’ is an adverb, and adverbs aren’t constrained in their position in the way that adjectives are.
I accepted that explanation when I first wrote this entry. However, reading it again recently, I asked myself: how on earth can that ‘below’ be an adverb? The traditional description of an adverb is ‘a word that modifies the meaning of a verb, adjective or other adverb’. Well, that ‘below’ doesn’t modify any word in that sentence.
So why, then, is ‘the table below’ acceptable? And what is ‘below’ in that phrase if it’s not an adverb?
I think I found an answer while reading about how linguists have been revisiting how some words are assigned to word classes (or ‘parts of speech’) in English grammar. One change they’ve introduced is to enlarge the class of prepositions. Traditional grammarians insist that a preposition must be followed by a noun or pronoun. This means, for example, that ‘before’ cannot be a preposition in either ‘that was before he died’ or ‘he’s been here before’, though it is a preposition in ‘before Tuesday’. Instead, in the first case, they classify ‘before’ as a ‘subordinating conjunction’; in the second case as an adverb; and in the third case as a preposition. Assigning ‘before’ to these three different classes in this way seems quite unnatural, as the constructions are otherwise very similar. Furthermore, saying that the ‘before’ in ‘he’s been here before’ is an adverb seems just as inappropriate as calling the ‘below’ in ‘the table below’ an adverb, and for the same reason – it doesn’t modify anything. Linguists have now removed the restriction about being followed by a noun or pronoun and ‘before’ is treated as a preposition in all three cases. If we accept this change, then we can argue in the same way that the ‘below’ in the phrase ‘the table below’ is a preposition, even though there’s no noun after it. And that is the ‘real’ reason why the phrase is grammatical.
An interesting side observation here is that the word above is treated differently from ‘below’, though you would think the two words are parallel. People are now accepting that ‘above’ can be an adjective – so ‘the above table’ is OK.
Avoid
See the below table/figure/…
Preferred
See the table/figure/… below
capable, capability
Avoid
the system is capable of handling up to ten requests
the system has capability to handle up to ten requests
provides the user with the capability to set preferences
Preferred
the system can handle up to ten requests
allows the user to set preferences
See also: able, ability
comprises of, is comprised of
Avoid
the program is comprised of the following projects
Preferred
the program comprises the following projects
consequence
Avoid
the system exhibits a degradation in response time
Preferred
the system responses are slower or the system is slower
Preferred
double-click
right-click
right-hand
left-hand
left-click or just click
(The Microsoft Style Guide recommends using ‘click’ and ‘right-click’ – even when, for a left-hander, ‘right-clicking’ may actually be done with the left mouse button!)
Double Negatives
not unexpected
not illegal
not impossible
not unreasonable
Avoid
it is not unreasonable to expect …
Preferred
it is reasonable to expect …
e.g.
Use only where space is limited (for example, in a table).
Preferred
for example
event
See in the event of
exist(s)
Keep this word for philosophical discussions about ontology and the meaning of life.
Avoid
a second server exists to provide back-up
Preferred
there is a second server to provide back-up,
or just
a second server provides back-up
experience
Almost always to be avoided (long-winded and pretentious!):
Avoid
delays in service may be experienced
our aim is to provide an enhanced user experience
during the system upgrade users may experience a degradation in response time
deliver a positive client experience
Preferred
there may be delays
our aim is to improve our user interface or to make our system easier to use
the system may be slower during upgrade
satisfy the client
following
Preferred
after
going forward
Avoid at all costs.
Preferred
in the future or from now on
iaw
Write in full
Preferred
in accordance with
i.e.
Use only where space is limited (for example, in a table).
Preferred
that is
All technical documents provide information or instructions. It’s tedious to keep using the word ‘information’.
Avoid
this document provides information regarding …
for more information regarding xxx, see …
this document provides information on how to …
Preferred
this document is about …
for more on xxx, see …
this document tells you how to …
or
this document explains how to …
Avoid
a new processor was installed, in order to improve execution time
Preferred
a new processor was installed to improve execution time
Reword – there’s almost always a simpler way to say it
Avoid
in the event of an unexpected system shutdown
Preferred
if the system shuts down unexpectedly
in view of the fact that
Preferred
because
inserted in
Preferred
in (not in all cases – use judgement)
In software environments, often thought to be a more ‘elegant’ word for problem or error. But it actually makes the meaning more obscure.
Avoid
Users should report any issues with the new release to the Help desk
Preferred
Users should report any problems with the new release to the Help desk
it’s, its
Incorrect
within the majority of it’s networks
when its appropriate …
when its been decided …
Correct
within the majority of its networks
when it’s appropriate … or when it is appropriate …
when it’s been decided … or when it has been decided …
-ize
Preferred
-ise
left hand
See double click
leverage, leveraged
Although these words are appropriate in certain contexts, don't use them simply as fancy substitutes for use and used, unless you want your documents to read like advertising guff.
Preferred
use or used (generally says it better)
located in/on/under/ …
Omit located
Preferred
in/on/under/ …
(as verbs)
login, logon, logout, logoff
setup, set-up
shutdown, shut-down
startup, start-up
timeout, time-out
Using a hyphen or running the two words together is correct and easier to read when you use one of these phrases as an adjective or a noun (eg 'set-up procedure' or 'a timeout of one minute'). But when you use the phrase as a verb, follow the pattern of 'shut up', 'sit down', 'hold on', and so on.
Avoid
Users are required to login
Next you must set-up your profile
Preferred
Users are required to log in
Next you must set up your profile
multiple
Avoid
where multiple users share a printer
Preferred
where more than one user/ several/a number of users share a printer
Nominalisations
(nouns from verbs)
implementation
termination
activities
reinstallation
Nominalisation is forming nouns from other parts of speech, particularly verbs – eg ‘implementation’ from ‘implement’. It’s very common in technical and business writing, and chokes the life out many sentences. A verb usually depicts something happening – ‘data flows’, ‘a window closes’ or ‘a computer crashes’ – and therefore evokes a vivid mental image. A noun, on the other hand, usually labels a thing and evokes a more static image of something that’s just ‘there’. If you nominalise a verb, the mental image becomes less vivid and you drain the sentence of some of its life.
When a piece of writing befuddles your brain, check out the verbs. Often you’ll find that the author’s nominalised all the strong, active ones and pieced them together with weaker ones like ‘is’, ‘has’, ‘proceeds’, ‘occurs’, and so on.
Avoid
responsible for the implementation of the package
following the termination of the program
monitoring activities undertaken by users of Tivoli
the contractor was tasked to undertake reinstallation of the package (or to take carriage of the reinstallation of the package )
Preferred
responsible for implementing the package
after the program ends [or, if you must, terminates]
monitoring what Tivoli users do
we asked the contractor to install the package again
not able to be
This awkward phrase is often a signal that someone’s trying to evade responsibility for something that happened by making it seem as if it was caused by a shortcoming in some inanimate object
Avoid
the fault was not able to be found
the deadline was not able to be met
Preferred
we couldn’t find the fault
we didn’t meet the deadline or – just maybe! – the deadline was unrealistic
on a daily/weekly/ monthly/ …/regular/ … basis
on a cost-benefit basis
Avoid
passwords are changed on a monthly basis
funding for travel is provided on a cost-benefit basis
Preferred
passwords are changed monthly
funding for travel is provided when benefits justify the cost
order
See in order to
prerequisites required
Preferred
prrequisites
provide
Some verbs can be used with both a direct object and an indirect object but provide isn’t one of them.
Avoid
Our aim is to provide the reader an overview of the project.
Preferred
Our aim is to provide the reader with an overview of the project.
Our aim is to provide an overview of the project for the reader.
First, let's be clear how I’m using the term indirect object. A traditional grammarian might say that all the three sentences quoted above have indirect objects, but current thinking is more restrictive. For example, in the two sentences ‘I gave my son a present ’ and ‘I gave a present to my son’, only the first is regarded nowadays as containing an indirect object. In the second, ‘my son' occurs inside a prepositional phrase ‘to my son’, which means it plays a quite different role in the structure of the sentence and doesn't have the characteristics required of an object.
Only certain verbs can be used, like give, with an indirect object in this narrower sense – these verbs are said to be ditransitive – and provide isn’t a ditransitive verb.
If we had the verb give in the original sentence, we’d be OK, because with give we can say ‘Our aim is to give the reader an overview of the project’. Here, the direct object is ‘an overview of the project’ is and the indirect object is ‘the reader’. The sentence is grammatical because the verb give is ditransitive, and so can have both direct and indirect objects. The indirect object is almost invariably put in front of the direct object, as in this example. But we can’t do this with provide because it isn’t ditransitive.
Here’s a list (probably not exhaustive, but perhaps exhausting) of ditransitive verbs: accord, afford, allocate, allow, appoint, ask, assign, assure, award, bake, bear, bet, borrow, bring, bring back, build, buy, call, catch, cause, charge, consider, cook, cost, cut, deal, deem, deliver, deny, design, do, draw, drop, earn, email, feed, find, fine, forbid, get, get onto, give, grant, guarantee, hand, hunt, keep, label, leave, lend, let in on, let know, loan, lose, mail, make, name, offer, order, owe, pass, permit, play, plug into, prescribe, profit, promise, purchase, put by, quote, read, refuse, regift, render, run by, run past, save, sell, send, serve, set, show, shower with, sneak, spare, supply, take, teach, tell, throw, wean off, win, wish, work, write.
presented
Avoid
the window was presented
Preferred
the window was displayed
prior to
Preferred
before
referenced
Avoid
a list of all sources referenced is provided at the end of the paper
Preferred
a list of all sources referred to is provided at the end of the paper
or
references are at the end of the paper
resource
Preferred
(when referring to a person) employee, staff member, or worker
right hand
See double click
set-up, set up
See login, log in
shut-down, shut down
See login, log in
singular or plural?
Often plurals can make for ambiguity. In the following example, it isn’t clear how many switches and how many routers there are per location. Using singulars with each can make things much clearer. Even when there’s no ambiguity, switching to a singular can sometimes help the reader to form a clearer mental picture.
Avoid
At key locations, the XYZ devices are connected between the switches and the two routers.
Preferred
At each key location, an XYZ device is connected between the switch and each of the two routers.
slash (or solidus)
Don’t write word1/word2 just because you can’t decide whether word1 or word2 is the right one.
start-up, start up
See login, log in
terms
See in terms of
timeout, time out
See login, log in
utilise/utilize
Preferred
use
via
Preferred
by/through/using
web site
Preferred
website
According to a discussion on the AustechWriter list, website is becoming more common. But you could probably still use web site if you prefer. Sources advocating website include http://www.askoxford.com/ … and the Macquarie dictionary, as well as various usage guides. But others favour web site, or even Web site. (The latter’s because Web is short for World Wide Web. However, The Times Style Guide and The Guardian Style Guide now even advocate world wide web and internet.)
who is/are, which is/are, that is/are
Avoid
users who are granted this role will have Support files, which are owned and controlled by …
Preferred
users granted this role will have Support files owned and controlled by …
within
Preferred
in
Examples & Recommendations