Words to avoid?

[Matthew Paul Thomas]

On Jul 6, 2006, at 12:27 PM, Mike MacCana wrote:
> ...
> On 7/5/06, Matthew Paul Thomas <mpt at myrealbox.com> wrote:
> ...
>> Similarly here, I think most people haven't heard of a CPU. And 
>> "Intel Core Duo" CPU type, for example, doesn't tell you whether it's 
>> a PC or a Mac. Perhaps "computer type".
>
> This is a hard one. Computer Type is still ambiguous.

Yes, it is by itself, but usually not when in context (followed by a 
list of types).

> But imagine the current SupportArchitectures page replaced by 
> something like this...
>
> There are three different versions of Ubuntu for different computer 
> types, depending on the CPU used in the computer.
>
> (Instructions on how to check CPU type from Windows)
>  (Instructions on how to check CPU type from OS X)
>  (actually, screw that, lets determine if from their BrowserID!)

ubuntu.com should certainly be doing that by default (not to mention 
choosing a mirror based on your IP address), but it still needs to let 
you choose architecture to handle the scenario where you're downloading 
from a different computer.

> ...
> > allow...to
>
> Replace with: Let.

Yep. The rest of your suggestions that I've snipped are also good ones.

>> , button, checkbox, conventions, dialog, dialogue, radiobutton
>
> Suggestions?

Here's an example, from the current Desktop Guide (I'm not picking on 
anyone, I have no idea who wrote this):

     3.  Select the Connections tab. Select the Ethernet connection
         interface from the list, then click the Properties button.
         Ensure that the button marked Enable this connection is
         checked. From the Configuration drop-list select DHCP/Static
         IP address, then click OK.

I suggest changing this to:

     3.  Click “Ethernet connection”, then click “Properties”.

     4.  Ensure “Enable this connection” is turned on.

     5.  If your ISP or network administrator has given you an IP
         address, set “Configuration” to “Static IP address”, then
         enter the address in the “IP address” field and click OK.
         Otherwise, set “Configuration” to “DHCP” and click OK.

That doesn't mention any types of control at all; it's clearer to refer 
to them just by their labels. It may be necessary to refer to control 
types where the control has only an icon, not a label.

(My revision is 13 more words overall, but only because "From the 
Configuration drop-list select DHCP/Static IP address" needed expanding 
to something helpful. On the other hand, the first sentence was an easy 
deletion, because the Connections tab always *is* selected when you 
open the window.)

> ...
> > empower
>
> Allows you to

Heh, keep going ... "let". :-)

> > enable
>
> Turn on

"Enable {noun phrase}" is usually better as "{verb phrase}". For 
example, "enable the Universe repository" would be better as "install 
software from the Universe repository".

"Enable you to", like "allow you to" and "empower you to", is better as 
"let you". For example, "Modules in the Personal category enable you to 
personalize your desktop" would be better as "Modules in the Personal 
category let you personalize your desktop", though it would be even 
better if deleted altogether (things like "change your desktop 
background" and "choose a screensaver" are realistic goals, but 
"personalize your desktop" is not).

>> following
>
> Then, the next, etc.

"Following" is a bit of a black hole -- a word or two around it usually 
need to be deleted as well. For example, "the following" is usually 
better as "this" or "these". And "In a terminal, type the following 
commands:" is better as "In a terminal, type:".

>> illegal
>
> Sggestions?

I should withdraw this word from the hitlist -- it is necessary when 
explaining legal issues like patent-encumbered formats. (I was thinking 
of things like "illegal operation", but they don't occur in 
documentation anyway.)

> ...
>> note
>
> Suggestions?

"Note that" can usually be deleted. "Note:" can be either deleted, or 
(if really necessary) replaced with an icon.

> ...
>> tab
>
> Actually think many people might know what tabs are, now Firefox is 
> around. What do you think would be better?

Right, I wasn't referring to places where they're considered a feature, 
but to places where they're part of the navigation to a feature. In 
those cases they can, again, be referred to by label rather than by 
type.

>> this section,
>
> This step.

"This section" is a symptom of a sentence that needs to be deleted.

>> tick, usage, user, wizard.
>
> Suggestions needed here too.

"Tick" can be "turn on". You can assume people know how to use a 
checkbox (and, iirc, some themes use crosses rather than ticks for 
cultural reasons).

"Usage" is a fluffy way of saying "use", though it might rarely be 
necessary if the sentence structure makes it unclear whether "use" is a 
noun or a verb.

"Wizard" can be referred to as "window". As with dialogs, people don't 
consciously care what kind of window it is.

>> In addition, for help intended to be read on-screen, I recommend 
>> avoiding:
>>
>> alternatively
>
> Instead?

On-screen help should normally list the most memorable way of doing 
something. Alternative methods should be in short and unobtrusive notes 
at the bottom, if they're mentioned at all. Such notes should start 
with useful classifying phrases like "If you need to do this 
frequently" or "If you prefer using the Terminal", rather than the 
vague "Alternatively".

>> consult
>
> Read / look at.

"Consult" is another black hole. If possible, the sentence containing 
it should be deleted in favor of a hyperlink. For example,

     In case you are not connected yet, consult the section called
     “Connect to the Internet”.

would be better as

     >   __Connecting to the Internet__

Similarly,

     Consult the Wiki Page on Restricted Formats.

would be better as

     >   __More about restricted formats__

If that's not possible -- that is, if the document you're referring to 
is published in paper form only -- "see" is shorter than "consult".

>> first
>
> Replace with nothing.

Yes, or with step 1 in a numbered list.

>> GNOME, GNU, KDE, guide, menu, next, welcome.
>
> Unsure what you're suggesting we replace these ones with.
> ...

GNOME, GNU, and KDE are irrelevant to on-screen help; in most cases 
they can be replaced with "Ubuntu", "Kubuntu", etc. (The pages 
specifically about them can be replaced with single paragraphs in a 
"How you can help" page.)

"Guide" is a symptom of help that isn't optimized for screen use.

"Menu" is another control name, and can usually be avoided.

"Next" is a symptom of a set of instructions that isn't in a numbered 
list and should be.

And "welcome" is a symptom of a sentence (or paragraph) that should be 
deleted.

Cheers
-- 
Matthew Paul Thomas
http://mpt.net.nz/