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 …

Page:

  1. chivo243 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!

    1. the spectacularly refined chap

      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".

      1. PickledAardvark

        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?

        1. Alien8n

          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".

          1. Mage 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.

            1. Timmy B

              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.

              1. Anonymous Coward
                Anonymous Coward

                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.

              2. Doctor Syntax 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.

            2. Chris Evans

              '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!

            3. Mage 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. LeahroyNake

            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 !

          3. Oh Homer
            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.

          4. ROC

            Re: Spoilers in Tech Docs!

            Ah, but these days, the action is "tap" - as on touch screens.

        2. Buzzword

          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.

        3. Jason Bloomberg 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".

          1. PickledAardvark

            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.

        4. J.G.Harston 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?

          1. dajames
            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!

            1. Mage 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

            2. Allan George Dyer

              Re: Spoilers in Tech Docs!

              @dajamesA - '"buzz saw" is a kind of saw. What kind of saw? The kind that buzzes.'

              Too non-specific. Circular, band, chain and jig saws all make some sort of buzz. Whick one are you on about?

          2. Doctor Syntax 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.

          3. david 12 Silver 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.

        5. Mage 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.

          1. Huw D

            Re: I hate the expression "click this"

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

          2. MJI Silver badge

            Re: I hate the expression "click this"

            Tap only applies to an old PC at bootup with a sticky HDD

            1. Alien8n

              Re: I hate the expression "click this"

              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.

        6. Nick Kew

          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.

          1. PickledAardvark

            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.

            1. Bent Metal

              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/ )

              1. Allan George Dyer

                Re: click this

                The meme adapted to the environment. Your or my perception of the quality if the environment (e.g. most people are ignorant) is irrelevant to how successful a meme is.

            2. Kevin Fairhurst

              Re: click this

              Sod this football / tennis malarkey, what’s your take on Greenalgh’s vs Galloways?

              1. Contrex

                Re: click this

                My other half's from Swinley - Greenalgh's - especially the butter ones.

          2. Mage 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.

          3. Sherrie Ludwig

            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."

            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.

        7. Timmy B

          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).

        8. Anonymous Coward
          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.

          1. This post has been deleted by its author

        9. Prst. V.Jeltz Silver badge

          Re: Spoilers in Tech Docs!

          do you click the doorbell or do you press it?

          I usually ring it :p

          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?"

            1. Nick Kew

              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?

            2. Doctor Syntax Silver badge

              Re: Onomatopoeic dinner parties...

              @TRT

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

            3. Anonymous Coward
              Anonymous Coward

              Re: Onomatopoeic dinner parties...

              Did I just wander into b3ta's Question of the Week?

          2. Mage 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. Norman Nescio Silver 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.

          4. Doctor Syntax 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.

          5. 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.

          6. Ozumo

            Re: Spoilers in Tech Docs!

            I text to say I've arrived as I don't like to trigger my millennial friends.

        10. Anonymous Coward
          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.

        11. IsJustabloke
          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

          1. PM from Hell

            Who are we writing for

            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.

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

Other stories you might like