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!
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 …
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".
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?
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".
"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.
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.
"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!
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.
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.
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".
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.
"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?
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!
"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.
If you think technical documentation is bad for PCs try writing process documentation for machinery. There's a reason the document seems to assume the user is a complete moron, occasionally the user IS a complete moron. But if you don't take into account that you need to tell a user not to touch a chrome plate that's heated to 200C and they then burn themselves it's the document writer to blame, not the idiot with no common sense.
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.
"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.
> 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.
(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/ )
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.
"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."
And I still "dial" a phone. My car horn "honks". A repetitive person still "sounds like a broken record" (coming back, I guess since hipsters discovered vinyl). So, yes, I may not move a mouse, but I still understand that moves a cursor to a specified location.
" 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).
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.
"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.
If there arethree things I hate in documentation its the use of obscure technical language which can be ambiguous to the reader, the use of over complex language when a simple phrase will do and grammar zealots.
We are not writing works of literature, these are technical guides, process documents and user instructions, they should;d be clear and concise and 'good enough' to do the job.
If a document is clear, unambiguous and correct then it is good enough, I'm not concerned whether the correct use has been made of the Oxford comma, or whether a technical team member who has worked hard to produce a good product has split an infinitive. Also think about your audience, not just in the language you use but also in the length of what you write. whilst a header explaining the purpose of a process may be appropriate for a design document its unlikely to be appropriate for the work instruction to be followed by a harassed agent in a call center who just needs the instructions (or script).
And if you ever do deliver products into a call center be sure to leave enough time for several reviews while the call center manager localises the instructions to suit the team culture. This is not the manager being difficult it is making sure that every thing agents see follows the house style and flow so mistakes are minimised. Your part of the review process is not to try and 'correct' the house style it's to make sure the technical elements remain correct.
Biting the hand that feeds IT © 1998–2019