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 December 2021]
The word below is not an adjective, so if you write ‘the below table’ you may be criticised for being ungrammatical. To avoid the criticism, I recommend changing it to ‘the table below’. Why would this version be acceptable when the other isn’t? Well, traditional grammarians tell us that below is either a preposition or an adverb; and they assert that in this new version below is an adverb, and it’s this that makes the phrase acceptable.
I went along with this analysis when I originally wrote this entry, but re-reading it now I have second thoughts. I do agree that ‘the table below’ sounds better, but I just don’t understand why anyone would say that the below in ‘the table below’ is an adverb. According to traditional grammar, an adverb is a ‘word that modifies a verb, adjective or other adverb’. But this below modifies nothing. One explanation I found for this seeming contradiction is that the phrase is really a shortened form of something like ‘the table mentioned below’, and below is an adverb modifying the elided verb. I don’t find this very convincing. But I found a more satisfying and credible path in the more modern approach in The Cambridge Grammar of the English Language. I can’t go into the detail here, but the authors describe a recent new approach to defining prepositions that allows for a preposition to occur without a following noun phrase, and under this definition the below in ‘the table below’ is a preposition.
Strangely, though, grammarians are starting to recognise above as an adjective, so you can get away with the exactly parallel phrase ‘the above passage’, though that was once similarly disputed.
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
prerequisites
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