"Click" vs. "Click on"...UGH!


#1

I’m unable to find any answers online which satisfies my Dilemma of the Day™. I prefer to economize by typing instructions such as “Click Submit” instead of “Click on Submit”–the extra “on” seems to be gratuitous, although it makes grammatical sense. What Would Marcia Do? :open_mouth:

What are your preferences, fellow tech writers? I’m curious.


#2

In this case, what would @torreybird do?

Write for our our users, not to a grammar guide. #writethedocs pic.twitter.com/onohxsNN2h

— Jim Anderson (@thecodewrangler) May 19, 2015

#3

In all the style guides I’ve ever been required to use, the requirement (not recommendation) is “click,” never “click on.”

But even some years ago, adventurous writers were suggesting that we could do away with the verbs altogether (especially if you think about the fact that there should be keyboard shortcuts for all those mouseclicks anyway … even though section 508 is more honored in the breach than in the observance … but I digress …).

Example:

File > Edit

or, in your case, Mo:

Do something or other something or other, then Submit.

Or, if as is increasingly likely, you’re writing for a web app, and if you must have a verb, “Go to” covers many bases (YMMV as always).

And then there’s also the touchscreen dilemma if you’re used to advising users to “click” … Right now my team afflicted with this situation has resorted to “tap or click,” but we are not happy with it.


#4

The alternative is to do as @joaofn would do – “Don’t document the UI. Document User Stores with the UI.”

aka, where the Submit button is obvious, don’t even bother telling the user to click (or select, or choose, or…)


#5

Although I personally like the idea that @bradamante proposed about getting rid of the verb, it’s not always possible if the buttons have been locked down. For exampe, a lot of my dialog boxes would say “Do something or other something or other, then OK.”

As for @mikejang’s suggestions, yes, if you don’t have to document it, don’t. I personally need a constant reminder to do this (or not do this)!

If you must document it, the standard I used to follow was “Click the Submit button.”

shudder

Our current style is “Click Submit”, which is us moving forward, so that’s my current jam.


#6

Even though you should avoid documenting the UI directly, you still need to give instructions to the user, on how to execute the procedure to produce the output they want.

Probably this works best with an example.
In this doc page, I tell you how you can manage the security of an infrastructure, by using roles to define user permissions.
I start the doc page by explaining what a role is, what they are used for. I also describe the roles that come out of the box with a clean installation of our product.

Then I need to explain to you:

  • How to create a role;
  • How to set the permissions the role will have;
  • How to assign users with that role, so that they are granted permissions.

In this last part, I really need to write stuff like:

To start creating a new Role, click on the ‘New Role’ link on the ‘Users & Roles’ page.

What I find is that 90% of my effort should be on understanding and explaining the feature (in this case a role), and how it can be used to achieve your goals (in this case, managing permissions).
Debating on whether to use “Click the Submit button” or “Click Submit” isn’t that productive since everyone has their opinions. So test your docs, and choose something your users can parse without having to read their whole text.


#7

We use Microsoft Manual of Style as a starting point for these decisions. I find it helps to have a style guide dedicated to tech comm. Minimally, it can inform your in-house style guide (even if that guide is in your head).

From page 264 of the 4th ed: “Do not use click on or click at.”

In the end, it probably doesn’t matter if you use “on” or not. I don’t think it gets in the way of meaning. Perhaps you can argue that it sounds more polished to remove it. This is why I like following a style guide. It removes ongoing debate and enforces consistency. It’s a good tool for our devs and marketing too, and it can save you lots of time answering the same questions over and over. :smile:

We use these resources:
Microsoft Manual of Style, 4th ed (2012)
Chicago Manual of Style, 16th ed (2010)
Webster’s Third New International Dictionary (Merriam-Webster), Unabridged (2002)

I’m not sure if Sun still publishes their style guide.


#8

Thanks for the Microsoft Manual of Style recommendation, @mdespres. This will be on my “must-investigate” list of books.

We have institutional style guide, and we follow the AP Style for our Intranet content. However, the technical conventions are Wild West, and as the lone tech writer in my organization, I feel more like a “responsible curator” of end-user documents, than a sheriff.

Hopefully Microsoft applied rigorous review process for their Manual of Style, unlike for some of their other written books (e.g., their official 70-680 Windows 7 Self-Paced Training Kit, whose first edition was sprinkled with 86 pages of errata).


#9

There is – or at least used to be – a good reason to avoid the “on” after “click,” too, besides a slightly cleaner user experience in English.

Localization. Although I’m not sufficiently informed about recent developments in natural language processing (other than that there’s been exponential growth in algorithms for it) and machine translation, to know whether this kind of distinction matters as much as it used to.

And +1 for MSTP as a resource for this kind of thing. Style guides are your friend here.

(I beg to differ with Joao on this point – and add this analogy. If your programmers don’t follow style guides/formatting conventions, just think of the mess you’d wind up with. Where I work, failure to apply templates/coding styles results in failed code reviews. Failure to follow style guides in docs results in broken doc builds. And both our code base and our doc sets are far too large, and the contributors too numerous and distributed, for us to be able to rely on in-person communication to maintain these standards.)


#10

I’ve sorta split the emerging Style Guide discussion into a different topic, ref Style Guides for Documentarians


#11

I, too, am a lone writer in what used to be the Wild West. Now, it’s only sort of wild.


#12

@mdespres Sun was bought out by Oracle, and I don’t think their tech writing folks have resurrected Sun’s “Read Me First!” guide. Just FYI… :slight_smile:


#13

If you use different styles for UI elements, then you don’t need to use additional words to indicate the UI element. So in @joaofn’s example, you would use “Click Submit.” Submit as the UI element is pretty clearly delineated.

As a sidenote, I’ve recently started at a new company. Wild West is an understatement. Much of the docs have been written by folks who are not necessarily well-trained in the sport of writing, well, quality docs. You can imagine my amusement (or maybe it was horror?) when I was sent a doc to review within the first couple of weeks of starting. All button elements were written as:

Click on the [NEXT] button to move to the next page.

Where [NEXT] was actually, I kid you not, a screen shot of, yup, the “Next” button. Which also meant the leading in the paragraph was all whack because the image threw the spacing off. And totally messed up the readability not to mention that if we did go out for localization you had the issue of two additional words (“the” and “button” to localize) plus every single image would have to be retaken.

Fortunately, he was amenable to redoing everything, and the next morning I had a brand new doc to read! :slight_smile:


#14

In the documentation project that I contribute to, we prefer to use, “select,” because we can’t be sure whether the person will be using a mouse or a touch interface.


#15

Hahaha!! This was the subject du jour on another list to which I belong. Someone had the dilemma of how do you document when your document is being single-sourced between a desktop application and a mobile app. And your style guide says to use “click” for desktop and “tap” for mobile. I said to use “select” because it can be used in either scenario and actually, it’s a generic verb that can be used because you don’t always use a mouse to select an UI button anyways.

The resultant discussion has been interesting. Some people have suggested to pick one, and then to add an intro paragraph explaining that when you say “click” you really mean “tap” if you are on a mobile device. What’s wrong with that? Well, when was the last time YOU read the docs in a linear fashion? How often do you even pay attention to any “introductory paragraphs”? Or even the conventions? Like, ever?

Then several others got all bound up in the fact that they use “select” for other actions, such as those to pick a menu option or a UI element.

Really, do you think your users will notice that your docs deviate slightly from some other application’s? As long as the instructions are clear and concise, and are consistent… it doesn’t matter. Pick one and stick to it.

Select is perfect. It works for people who don’t use a mouse (including those with accessibility issues), for both desktop and mobile apps, as well as other touchscreen devices.


#16

I’m dealing with this right now. I don’t even like the word “click” as it seems informal to me. I am using “select” instead, but now I am wondering what to do when something calls for you to “double click” a button :slight_smile:


#17

Right-select doesn’t sound so good either :slight_smile:


#18

I always avoid the verbs that lock you into a particular user interface–when that app goes mobile, the customer won’t be clicking. Just another vote for simplifying to “Submit” (assuming the UI makes how to submit obvious). I’d include the final step if the customer will lose their work if they don’t submit their info (see how I didn’t talk about the UI there?).

Good luck, these things are never easy to decide, and there are always exceptions. But mentioning the label instead of the verb and the device type saves you revising it when they add mobile, or voice, or whatever the next thing is.