back to article Consultant misreads advice, ends up on a 200km journey to the Exchange expert

Another Monday has landed with a thud – no doubt even more so for those of you in the States coming down from a weekend of Thanksgiving revelry. But it also means it's time for the latest instalment of Who, Me?, where Reg readers write in with their confessions of tech disasters to cheer you up. This week, we have a lesson in …

Silver badge
Facepalm

Spoilers in Tech Docs!

For once I wouldn't mind a spoiler, instead of instructions that read "but first.... " after you've already taken a first step!

69
0

Re: Spoilers in Tech Docs!

I've been on both ends of this, both having to write procedural guidance and follow rarely used stuff for e.g. end of year processes. I can sympathise with the authors, it's very difficult to write technical documentation that essentially boils down to a sequence of steps in a manner that does not sound robotic. Your intiial draft often ends up as "select this", "click this", "click this", "click this"... and the resulting prose sounds awful even if broken up by bullet points or numbered steps. It's also quite difficult to follow since all the steps seem so much alike and can be confused - at this dialog do you follow the "click OK" step or the "click cancel" step?

You do try and mix up language and sentence structure as much as possible but there are rules that you are best rigidly following, such as as here, alway presenting steps and information in the order it is needed. Out of order even within the same sentence, such as "Do this after having done that..." is guraranteed to cause errors because people will have done "this" before reading ahead the few extra words which cover "that".

58
0

Re: Spoilers in Tech Docs!

I hate the expression "click this". "Click" is an onomatopoeic verb or noun; "click" is the noise that a mouse or trackpad button makes when it is operated.

The GUI should be a metaphor for the physical world. In a GUI, users press buttons, slide controls, grab objects or select objects etc. When visiting friends, do you click the doorbell or do you press it?

9
37
Silver badge

Re: Spoilers in Tech Docs!

A recipe I like is to write the techie explanation in the middle.

Above it, a simple note "for quick step-by-step guide, scroll down to <anchor>".

Below it, those step by step instructions. Any critical gotchas refer back to the explanation.

But then, the kind of instructions that say "click OK or cancel" don't feature in my world. I'll google when something is a bit less obvious than that.

4
0
Silver badge

Re: Spoilers in Tech Docs!

While true you have to remember the target audience for any documentation. You'd be surprised how many people ask "what does press button mean?" and when presented with the answer reply "well why didn't you just say click it then?"

Your average user associates "click" with the sound the mouse makes when they press the virtual button on the screen. It's all very Pavlov, but yes, if you want to get your point across to the average user it's safer to say "click button x" than it is to use the more logical "press button x".

30
0

Re: When visiting friends, do you click the doorbell?

I take the choo-choo to my friends' house where I ding the doorbell, we clink our wine glasses, then scoff & chomp our food. All very onomatopoeic.

35
0
Silver badge

Re: Spoilers in Tech Docs!

do you click the doorbell or do you press it?

Where "press" is a physical action which involves pushing on the doorbell button.

Using "Push on the OK button" may be fine for a touch screen but not so clear when using a mouse.

"Click on OK" is a good enough shortform for "Move the mouse pointer over the OK button and push down on the mouse button which will make a satisfying click sound".

26
0
Silver badge

Re: Spoilers in Tech Docs!

When I first started writing code I was taught to do something that has long been very useful for avoiding this type of incident (I've "graduated" to writing user documentation and many other things).

You start with a "Header" that documents what the procedure does, what it requires as input and what it generates as output. It's been years since I've seen anyone writing or coding this way - I think this explains a lot.

24
0
Bronze badge

Re: Spoilers in Tech Docs!

My favourite thing is process notes that, after three pages of detailed steps say "the previous 32 steps are now all run with the batch file in [location], just run that."

33
0
Silver badge

Re: Spoilers in Tech Docs!

"do you click the doorbell or do you press it?"

Neither, I ring it. You should use the vern that describes the ****ACTION****, not an incidental implementation-specific method of getting to that action.

You select YES, you don't click on YES. You may not have a clicker, your clicker may not make any clicking sounds, you may not want to use the clicker you may want to use the keyboard or a touch screen. It's this american moronism that does things like call a mobile phone a one-specific-implementation-of-a-mobile phone, and "buzz saw" - what the hell is a buzz and why and/or how would I want to be sawing it?

29
7

Re: Spoilers in Tech Docs!

I had a quick look at the oldest documentation I could find for GUIs -- Lisa 7/7 for the Apple Lisa 2 -- and it uses terminology similar to that described by Jason Bloomberg. It actually says things like "click OK".

So the convention has been around for at least 34 years... It still bugs me.

13
3
Silver badge
Paris Hilton

Re: I hate the expression "click this"

I also hate "Tap", strangely now often used on instructions for Windows or Linux.

13
0
Silver badge

Re: "click" with the sound the mouse makes...

"click" with the sound the mouse makes when they press the virtual button on the screen.

My mouse click has never in over 30 years of using GUIs resulted in a sound effect when using "virtual buttons". They USED to invert the left & top with bottom & right to visually indicate clicked or held down. Sadly mostly the now don't. "FLAT" is stupid.

24
0
Silver badge

Re: click this

You need to get over it. Language evolves.

Click may have some historic association with a sound, particularly in an era when computer devices had horrible artificial "click"s that were supposedly reassuring to people making the transition from mechanical typewriters. But that's now historic, and (in a computing context) the word "click" is now an action.

20
0
Silver badge

Re: Spoilers in Tech Docs!

" When visiting friends, do you click the doorbell or do you press it?"

Or... Like I do... Ring the doorbell.

It's pretty much well known by everyone that "Click on" means move the mouse to that the pointer is over the correct position and depress the left button. Good lord, we're a pedantic lot sometimes (I certainly include me in that).

12
0
Silver badge

Re: "click" with the sound the mouse makes...

""FLAT" is stupid."

Ironically many of the "flat" buttons in Windows 10 do actually change in a looks like they are being pressed way if you click on them.

I just noticed as I was curious.

7
0
Silver badge
Headmaster

Re: Spoilers in Tech Docs!

You select YES, you don't click on YES.

"Click on YES" is shorthand for "click the (primary) mouse button while the pointer is over the "Yes" button on the screen". As English Usage it's not lovely, but it's pragmatic and most people -- most people who know what a mouse is, anyway -- know what it means.

Note that you can "select YES" by moving the focus to the button control with the caption "YES", but that doesn't activate it, you have to press the space bar or Enter key as well to do that.

... and "buzz saw" - what the hell is a buzz and why and/or how would I want to be sawing it?

A "buzz saw" is a kind of saw. What kind of saw? The kind that buzzes. "Buzz", here, is used as an adjective to describe the kind of saw being mentioned, and will be understood by anyone who knows what a buzz saw is.

If you expect every adjective+noun pair to work the same way as "fly trap" (a trap for trapping flies) as you seem to expect "buzz saw" to do, then you will find many common phrases -- such as "hot tap", "front door", and "light bulb" -- rather confusing!

21
0
Anonymous Coward

Re: Spoilers in Tech Docs!

what if you have to state left click or right click... left press or right press?

I think I prefer click in that instance.

4
0
Silver badge

Re: Spoilers in Tech Docs!

do you click the doorbell or do you press it?

I usually ring it :p

5
0
Silver badge

Re: Spoilers in Tech Docs!

You start with a "Header" that documents what the procedure does,

Absolutely essential while writing Java, but if you go quite a bit further you'll have something that anybody can understand and, better yet, YOU will understand if you need to tweak it in a year or five.

  • The class-level description needs to say what the CLASS is intended to do, no more and no less, though it may also be a good place to describe the meanings of any public constants
  • The method level descriptions can be quite brief. They should give guidance about when to call them, unless they're a simple getter or setter, but should not paraphrase any of the @param annotations
  • This documentation must be run through javadoc and read to check that it makes sense

If you don't do all the above BEFORE you write more than than a skeleton class and methods then (a) you probably haven't thought the class design out properly and (b) for sure you'll piss off future developers.

The same goes for writing C except the the 'class' level stuff goes at the top of the source file and you need to check what's in your comments by running the code through your chosen documentation tool.

Last but not least, if the class or function package does anything thats even slightly complex write a test harness and a set of regression tests that get put into version control and/or backed up with thre code it tests. A PHB will tell you this is not necessary and/or a waste of time but IME he will be very wrong. A well-considered set of regression tests (covering simple usage, edge cases, and as much misuse as you can imagine) will save a LOT of wasted time and swearing. The test harness need merely take a line such as

methodname param1 param2 ... # comment saying what you expect

and split out the method name and parameters into an array of, say, strings and ints before executing an if.. then.. else.. totem pole which calls all the methods and displays all results interspersed with a listing of the test script. Dead simple: no conditionals needed because you can simulate that by the order of method calls in it.

If you're clever, you'll put all the script reading, parsing and printing into a driver structure that can run scripts against plugins that are specific to the class being tested and add something that compares test output with a set of expected results: a regression test pass is when the comparison produces no output.

7
1
TRT
Silver badge

Re: Onomatopoeic dinner parties...

Or ring the bell and start taking a piss on the Welcome coir and when the door opens ask them "How's that for an on-a-mat-a-pee'er?"

18
0
Boffin

Re: Spoilers in Tech Docs!

I'm usually the one writing the batch file for the previous 32 steps & a few more on top usually.

4
0
Def
Silver badge
Happy

Re: Spoilers in Tech Docs!

When visiting friends, do you click the doorbell or do you press it?

I usually have to call them to get them to open the door because they're too lazy to write their name on a piece of paper and stick it next to the button for their apartments.

6
0

'Slab in'

"They USED to invert the left & top with bottom & right to visually indicate clicked or held down. "

I've heard that being called 'Slab in' i.e. trying to visually show that the button has been pressed in. The strange thing is I sometimes find Windows does change the icon to 'Slabed in' but doesn't do the action!

4
0
Silver badge
Meh

Re: Spoilers in Tech Docs!

@PickledAardvark

You may hate it but intended audience for instructions that include such phrases know exactly what is meant by it and IMO clarity of purpose trumps all other considerations

7
0
Def
Silver badge

Re: "click" with the sound the mouse makes...

Ironically many of the "flat" buttons in Windows 10 do actually change in a looks like they are being pressed way if you click on them.

The way they push in also changes according to where you clicked, or if you moused out and back in, where the mouse re-entered. Click on the left and the left side is pushed in more than the right. Re-enter from the bottom and the bottom is pushed in further. Re-enter from the top the top is pushed in further.

4
0

Re: Spoilers in Tech Docs!

You ring the doorbell. You click the mouse. You boil the kettle.

Oh, didn't you realize "boil" is onomatopoeic? Ah well. Carry on pretending to be an authority on English.

10
2

Re: Spoilers in Tech Docs!

"it's very difficult to write technical documentation that essentially boils down to a sequence of steps in a manner that does not sound robotic"

You're using a GUI. Get used to robotic-sounding instructions. If you don't like them, explain to the manufacturer that you prefer proper grown-up scripts because you don't like your instructions to sound robotic.

5
1
Silver badge

Re: Onomatopoeic dinner parties...

Or ring the bell and start taking a piss on the Welcome coir and when the door opens ask them "How's that for an on-a-mat-a-pee'er?"

Is that usage somewhere in ISIHAC's Uxbridge English Dictionary, or is it just my imagination?

5
0

Re: I hate the expression "click this"

Ah, the assumption that you're using a touchscreen device...

1
0

Re: click this

"You need to get over it. Language evolves."

No. Evolve doesn't mean what you suggest.

If you apply Darwin ideas, a word would change to survive in usage for the mere purpose of survival. Words aren't organisms. Words don't evolve.

People change and language changes. And sometimes people get it wrong.

Failure to comprehend the distinction between uninterested and disinterested amazes me. Are we supposed to toss away the difference because the two words are "about the same"? 'Cos some people muddle them up?

Uninterested: I live in Wigan and follow Rugby League. I am uninterested by Manchester United because I have no interest in Association Football. Not bothered.

Disinterested: Owing to my acute eye sight, I earn a living as a tennis umpire. The sport bores my tits off so I am uninterested. I watch the players and when I proclaim that somebody played a foul, I am disinterested.

Evolution isn't change.

3
9
Silver badge

Re: "click" with the sound the mouse makes...

Also my mouse (pointing pebble a better name?) has a tactile click on the buttons or wheel press, none have ever made an audible click. The so called "haptic" feedback on phone virtual button presses is useless, nor has any phone had a decent click sound. Some manage the DTMF tones on keypad.

2
0
Silver badge

Re: computer devices had horrible artificial "click"s

None I've had in 40 years had any sort of "artificial clicks." Some decent keyboards had a faint mechanical click. You COULD turn on an artificial keyboard "click" on some BIOSes, but I never knew anyone that did and I knew plenty of people that had used typewriters and still used them in parallel up till start of 21st C for specialist tasks.

2
0
Silver badge

Re: shorthand for "click the

"You select YES, you don't click on YES.

"Click on YES" is shorthand for "click the (primary) mouse"

Indeed! "select Yes" would be Tab / reverse Tab or arrow navigation to select the "yes" button, that then could be executed by pressing Enter/Return key

4
0
Silver badge

Re: Ringing Doorbell

"click the doorbell or do you press it?

I usually ring it :p"

Ringing works if button or chain operated.

You can only press the button for a doorbell.

3
3
Bronze badge

Re: Spoilers in Tech Docs!

do you click the doorbell or do you press it?

At one of my friends' dwellings, I pull the porcelain handle hanging down from the porch. The handle is attached to a wire cable in a conduit, and somewhere in the depths of the house a physical bell on a spiral spring jangles. Another friend has beside the entrance door a sprung knob which you pull and release to set a bell ringing. That confuses a lot of people, even though the brass around the knob is engraved "Pull to ring".

I remember visiting someone in a flat somewhere on the continent, and the doorbell was a rotary device - you rotated it, and a bell on the other side of the door, much like an old-style bicycle bell, trilled away. A similar device I have seen is a clockwork doorbell, which has a conventional button to push, but which is wound up by turning the bell on the inside of the door. If you forget to do this periodically, it falls silent.

I have yet to see a doorbell operated by a lever, but I expect it is possible. Or even a pneumatic plunger to operate a whistle.

5
0
Bronze badge

Re: Spoilers in Tech Docs!

'Your average user associates "click" with the sound the mouse makes when they press the virtual button on the screen.'

You also need to tell them to 'touch' an icon / area of a touchscreen rather than 'press'... some people press way too hard !

1
0
Bronze badge

Re: Spoilers in Tech Docs!

You ring the doorbell. You click the mouse. You boil the kettle.

Oh, didn't you realize "boil" is onomatopoeic? Ah well. Carry on pretending to be an authority on English.

<pedant>I generally boil the water in the kettle, not wanting high temperature metal and/or plastic vapour floating around the kitchen.

I wouldn't say the word boil is onomatopœic - for me at least, boiling water doesn't sound like boil...boil...boil. You might argue that 'kettle' is a meronym for the combination of the utensil used to boil the water and the water itself (and also a synecdoche). </pedant>

For me, the vast majority of mice I have used emit a click sound when one of the mouse buttons is depressed, so it is entirely reasonable to use that as a description of the action needed to activate an on-screen button; just as when using a touch sensitive screen, the action people use to activate on-screen buttons is to tap the screen. I find silent mice take some getting used to, as I am accustomed to getting the auditory feedback. One of the problems I have with 'flat' interfaces is the lack of feedback when you try and activate sensitive areas. If you are not sure if your tap has been registered, you can tap several times to try and get a response, which can be less than useful if your taps are buffered and applied later.

6
1
Silver badge

Re: Spoilers in Tech Docs!

"You select YES, you don't click on YES."

Drop-down list, Run the pointer down the list. As it traverses the list it selects each item in turn. Leave it on the item you want. Many (?most) people would reckon you'd selected the item but nothing will actually happen until you take a further action which, at least on this laptop makes a loud, and AFAICS, purely mechanical clicking noise. But don't call it a mouse pointer 'cause it's a trackpad.

4
0
Silver badge

Re: "click" with the sound the mouse makes...

"I just noticed as I was curious."

There's a limit to my curiosity and trying WIndows 10 to find out is beyond it.

6
0
Silver badge

Re: Spoilers in Tech Docs!

"I usually ring it"

You may ring the bell but you probably just press the button at the door.

2
0
Silver badge

Re: Onomatopoeic dinner parties...

@TRT

You should be ashamed of a pun like that. Have an upvote.

3
0

Re: click this

> No. Evolve doesn't mean what you suggest.

Evolve, as you note, didn't originally mean 'simply change'. But it *is* how very many people now use the word.

It evolved...

(and yes, some such changes drive me nuts. But many folk use new words or forms for successful communication; so much so that they are often added to the OED - https://public.oed.com/updates/ )

6
0
Silver badge
Headmaster

Re: Press button X!

Tutor: Press button X!

Student: [Reaches up and touches the screen]

Tutor: No, no, that won't work. It's not a touchscreen display. You need to press it with the mouse.

Student: [Lifts mouse up to the display]

Tutor: No, no. Good grief. OK, let's start again! Move the cursor over the button!

Student: [Reaches up to the screen, touches the blinking cursor in the command terminal, then tries to drag it over to the X button]

Tutor: Oh for the love of... Look, just move the mouse pointer over the X button by dragging the mouse across the mouse mat then briefly pressing down on the left mouse button!

Student: Oh you mean "click the button"? Why didn't you just say so?

Tutor: [Shoots himself in the head]

Sometimes you just have to accept that language evolves to reflect the way it is actually used by the majority. This is exactly why dictionaries are continually revised.

NB The above scenario is a real example drawn from my personal experience (although I didn't actually shoot myself). The "student" in question was actually my elderly mother, who I was coaching over the phone, desperately trying to retrieve somebody's contact information from my PC. This was many years before smartphones and cloudy storage.

9
0

Re: Spoilers in Tech Docs!

And this is why those of us who are technical writers (to a greater or lesser degree) struggle with techs(I'm one of those myself) and UI designers who adhere to a platonic ideal of how a GUI "should" be perceived versus how it's actually interacted with by those who use the thing. (By the way, that concept of a GUI is merely an analogy, and as such, subject to its own inconsistencies.)

The action you carry out when you select an object on GUI is not a "press" when using a mouse, it's a "click". This is what the users actually experience when they do the action (you're right that it's an onomatopoeic verb). Now, on touchscreen devices, you don't "click", but since you're not physically interacting with the thing on the screen either, I'd argue that you're not doing doing a (button) "press" either.

Personally, I prefer to just use the word "select" in all instances, as repetitive as it gets. If there are options, I often use the word "choose".

The adherence to platonic ideals when writing technical material without considering the audience is what has made it famously difficult to digest by the average punter, and even technical readers. Using the word "click" to describe the action of selecting something is not actually *inaccurate* in terms of eliciting the required action - it's an accepted colloquialism for selecting something on screen. As long as your phraseology isn't actually *misleading* the reader, it's always better to make documentation decisions in favour of proper understanding of the objective rather than pedantry. It is actually possible to write in a clear way (that might slightly elide some concepts) without losing the appropriate level of accuracy *for the audience*.

8
0
swm

Re: Spoilers in Tech Docs!

"When visiting friends, do you click the doorbell or do you press it?"

No, I ring the doorbell.

1
0
swm

Re: Spoilers in Tech Docs!

"Just dial 555-1212"

Has anyone seen a dial telephone recently? I have an old dial telephone and my granddaughter (13 years old) struggled to make a call on it (as did a full professor at my college years ago). My 3-year old granddaughter loves the dial phone to play with.

5
0

Re: Spoilers in Tech Docs!

ring the doorbell.

1
0

Re: Spoilers in Tech Docs!

ring the doorbell.

Press the button.

1
0
Bronze badge

Re: Spoilers in Tech Docs!

"You select YES, you don't click on YES."

You use the TAB key to select YES, then you trigger the YES action by pressing the [ENTER] key.

[SELECT] is already a defined action, different than [CLICK]. You can't have that word, and it's not what you want anyway.

1
0

Page:

POST COMMENT House rules

Not a member of The Register? Create a new account here.

  • Enter your comment

  • Add an icon

Anonymous cowards cannot choose their icon

Biting the hand that feeds IT © 1998–2018