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 …

  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.

        12. cream wobbly

          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.

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

            1. Anonymous Coward
              Anonymous Coward

              Re: Spoilers in Tech Docs!

              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.

              You'll like a portion of any web/html interface I design then.

              Someone long ago (just when tablets were starting to get popular) complained about that sort of thing, and ever since I've used the 'onclick' functions to change the button and/or the border briefly to give a visual cue that it's been touched. Sometimes a colour change, sometime a border change (representing physical depression), but a change none the less to make it clear it's touched.

        13. Trixr

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

        14. swm

          Re: Spoilers in Tech Docs!

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

          No, I ring the doorbell.

        15. wayne 8

          Re: Spoilers in Tech Docs!

          ring the doorbell.

        16. wayne 8

          Re: Spoilers in Tech Docs!

          ring the doorbell.

          Press the button.

        17. ratfox

          Re: Spoilers in Tech Docs!

          The GUI should be a metaphor for the physical world.

          I strenuously object.

          Maybe people thought that skeuomorphic design was a good idea when computers were new and users were terrified of using new concepts. But by now, imitating the physical world is more a limitation than anything.

          Though I do agree that we need a better word than click, if only because nowadays people mostly tap.

          1. Anonymous Coward
            Anonymous Coward

            Re: Spoilers in Tech Docs!

            Though I do agree that we need a better word than click, if only because nowadays people mostly tap.

            Need a better word than 'tap' as well. Unless you'd like me to tap your son's icon?

            (Mine's the rather dingy looking trench coat)

        18. Anonymous Coward
          Anonymous Coward

          Re: Spoilers in Tech Docs!

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

          How dare you presume I have any friends.

      2. Nick Kew

        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.

      3. Version 1.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.

        1. Killfalcon Silver 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."

          1. The Oncoming Scorn Silver badge
            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.

        2. Martin Gregorie

          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.

      4. cream wobbly

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

        Re: Spoilers in Tech Docs!

        So true.

        Click, click, click... see this is one reason to prefer command line, copy-pasted, geez, gasp, even bash-ed configuration mechanisms ;-). I remember colleagues shuddering about the horrors of hour long Sharepoint deploys... how daft.

  2. Dave K

    The story does appear to end mid-way through. What sort of issues were caused by running this procedure on one of the Exchange servers, and how was it fixed? Making a screw-up is all fine and well, but it helps if we can properly visualise the fireworks following this!

    1. Stevie

      Vizualizing

      Stand By Me.

  3. Anonymous Coward
    Joke

    Someone should have told him...

    That the warnings come AFTER the spells...

  4. Anonymous Coward
    Anonymous Coward

    Bad advice

    A member of another team was having some issues with data in an oracle database we host so a customer was having issues

    Person spoke to the developers who are in a chocolate producing country with mountains

    They gave her a script to run to "fix" the issue.

    Turns out, they had provided a script that dropped the schema, suddenly, the customer could see no data, at all anymore - frantic scrabbling for restores and then replay all the data made for an entertaining day for some people.

    A number of things came out of this

    a) Support team having oracle admin rights

    b) proof reading scripts that are provided rather than believe what has been given is right

    c) an oracle DBA should be the one doing oracle related stuff.

    d) remove oracle rights from everyone but the DBA's

    Anon

    1. jmch Silver badge
      Devil

      Re: Bad advice

      "... in a chocolate producing country with mountains."

      https://www.worldatlas.com/articles/top-10-cocoa-producing-countries.html

      https://en.wikipedia.org/wiki/List_of_elevation_extremes_by_country

      so, Ecuador or Peru? :)

      1. Anonymous Coward
        Anonymous Coward

        Re: Bad advice

        I did say chocolate producing, not cocoa producing :D

        End product not source product!

        https://www.telegraph.co.uk/travel/food-and-wine-holidays/the-surprising-country-that-produces-the-most-chocolate/

        So....... :-P

        1. Gene Cash Silver badge

          Re: Bad advice

          Since I'm in the Land-Of-Shite-Chocolate, any employees visiting from Europe are commanded "BRING US CHOCOLATE!"

          One delicious surprise was Russian chocolates containing 100-proof vodka.

          1. Antron Argaiv Silver badge
            Thumb Up

            Re: Bad advice

            I'd be highly skeptical of ingesting anything from Russia, given recent events.

            1. dajames

              Re: Bad advice

              I'd be highly skeptical of ingesting anything from Russia, given recent events.

              Ooh, a lovely box of Novi Chocks .. how nice!

            2. The Oncoming Scorn Silver badge
              Stop

              Re: Bad advice

              The last Chocolate liquer from Russia (Or somewhere of that ilk) still had the prime ingredient of the cabbage leaf floating in it.

          2. Olivier2553

            Re: Bad advice

            One of my recent discovery is a chocolate made by Lindt with 99% cocoa. It is quite bitter (but I drink my coffee without sugar) but has such a strong taste that you still fill it in your mouth 30 minutes later.

            The caramel and sea salt is great too, but so far I could only find it once.

            1. jmch Silver badge
              Thumb Up

              Re: Bad advice

              "The caramel and sea salt is great too, but so far I could only find it once."

              I love the 70% + sea salt ones. Luckily I live in Switzerland and they're stocked by most big supermarkets :)

            2. DuchessofDukeStreet

              Re: Bad advice

              @Olivier2553, if you're in the UK you can buy it mail order from Lindt

              https://www.lindt.co.uk/shop/our-brands/excellence/excellence-dark-caramel-and-sea-salt

              I also know you can buy it in Waitrose (and allegedly Sainsburys and Tesco but the butler doesn't shop at those establishments).

      2. a pressbutton

        Re: Bad advice

        I hope anon gave them a really hard stare

      3. Anonymous Coward
        Anonymous Coward

        Re: Bad advice

        so, Ecuador or Peru? :)

        Vietnam?

    2. DuchessofDukeStreet

      Re: Bad advice

      Data scripts...wonderful things! Some years ago I was working on a data migration for a corporate demerger (customer was an arse, objected to me doing terrible things like wanting to use encryption on files relating to HR and payroll records) and the functional techie came up with a script to do the extract. It looked good in theory but something I couldn't identify made my nose twitch so I ended up taking it to the lead Oracle DBA (who was the kind of BOFH that didn't believe anyone should be allowed near "his" systems: developers, support analysts and users alike) who read it through in silence and then explained in no uncertain terms exactly how much damage it would do to the platform if executed, followed by exactly how much damage he proposed doing to its author. We negotiated (he was okay if you asked him for things in the right way really) and I gave it back to the techie with the edited highlights.

      While the techie was reconsidering his life choices, I decided to google the problem - only to discover the EXACT wording of the script (formatting and spelling mistakes included) in the very first returned site. Which is how I first discovered stackexchange.

  5. Lee D Silver badge

    Apparently, the only person in the world who actually worries when something says things like "Just delete the organisation" or "Just upgrade the entire domain" or "Just format the entire drive" is me.

    Nobody else seems to actually care a jot about the implications, nor why an ENTIRE organisation has to be deleted to fix some problem.

    Do people seriously do these things without question? I mean, it would always have raised red flags to me - as a junior I wouldn't have wanted to be sitting there deleting things in Exchange, as a senior I wouldn't want to be deleting organisations because something on the Internet said so (MS KB or not!).

    I have a setup at the moment where we have an Exchange server on the domain, except the ORIGINAL Exchange server went ape and some idiot replaced it without cleaning up. The old one is still there, the old DB is still there, there are references in DNS to the server that no longer exists etc. And things like some of the special mailbox accounts only appear on *some* of the DCs. If you read MS KB, they say "just delete it" and/or "just re-run setup". Though I'm quite sure that works in many instances, I'm not an idiot to trust it.

    Three times now, I've taken the whole domain setup down, and done everything recommended to get rid of that old server reference (even spinning up a matching-hotfix-level server, migrating mailboxes, trying to clear the origianl etc.). Three times it just trashed the domain or the Exchange setup. The only difference is a) I didn't do it blindly while in production, b) I snapshotted every VM on the network before I did it, c) I did it on an isolated copy of the production network, d) I was therefore able to see the destruction, try to fix ti, but then roll back the entire state of the test network in seconds, no harm done, without ever touching production.

    The *proper* solution is a complete Exchange wipe-and-reinstall, but given that Exchange has worked quite happily in that state for years before even I came along, I'm going leave that until we need to upgrade/migrate anyway. It's not like I'll actually lose any mailboxes. Because I'm not idiot enough to "just press the button".

    I often get asked to go into a charity to help them with their IT. The first instance was for a children's hospice. Can I just get rid of some icons from their desktop setups and change a couple of settings? So I go and have a look. Their systems are managed somehow. They have connections to remote-sites, remote-backups, and other things. Though I'm assured they are their systems "and other branches just work as our backups", and they have administrative passwords, I look a little deeper and the first thing I check is "can I undo any changes I might make?". I see that those backups aren't doing anything (0-byte log files, etc.). As they want me to make changes to all kinds of user settings that aren't just tiny little things, I don't proceed and dig further.

    Of course, I could have piled in, made the changes, tweaked the bits and ran. But the deeper I dug the more I found. And then when asked why they wanted to make these changes and what work was done on the office machines that I was looking at, the answer: "Oh, it just collates and records all the end-of-life medication that we give the children so we don't make a mistake and accidentally kill one of them". It's not long before I'm backing out of there with hands raised, telling them that they need to get a proper support contract and someone to look at their entire system.

    (Happy to take that responsibility, but not without a formal contract and insurance on my behalf!).

    Don't be the guy who "just thought he'd try it". Be the cautious guy. The one who warns. The one who warns even when being yelled at to "just do it". And then, even if you're made to do it and it all goes wrong, you can just say "Oh... look... I wonder why I was cautious and told you that was a bad idea..."

    1. Anonymous Coward
      Anonymous Coward

      We had orphaned an orphaned exchange server still hanging around for years every now and then creating a warning message when trying to do a task. Could never get rid of it without a complete new install and then copy across - which causes its own problems sometimes with X.400 addresses.

      Nothing compared to very minor database irregularities which can cause days of issues. A couple of seconds of lost connection to an exchange mailbox data store can render untold issues. You'd think with a decent transaction logs and the original db it could quite easily sort itself out, but on the few occasions when it happened I had to do a Hard-Fix on the database after trying for days to do the standard recoveries which caused significant damage to the mailboxes (although the db became mountable again) and the only fix then was to move the mailboxes and allow a very large number of corrupt messages to be skipped.

      SQL has always been far more robust to data errors in my experience.

    2. My-Handle

      Only a couple of times in my career have I been told "just do it!" by a manager in the face of my warnings of dire consequences. Both times, I've answered: "I will do as you ask, but I will need your request in writing as well as an acknowledgement that I warned you about X, Y and Z". I was quite happy to tell them that I needed it to cover my arse when things inevitably fell over. Most of the time, the managers' requests mysteriously went away. For the one that didn't, the manager did at least stop and think through what he was asking before pushing ahead.

    3. wyatt

      Customer signed change controls, they have their benefits!

    4. jmch Silver badge

      "things like "Just delete the organisation" or "Just upgrade the entire domain" or "Just format the entire drive" "

      Personally I find that the word "just" immediately rings alarm bells. It implies a confidence (which is almost always utterly misplaced) on part of the speaker/writer that this is a trivial thing requiring little to no effort on your part, and also sneakily implies that your unwillingness to do said thing is due to incompetence, bloody-mindedness or both.

      Just start paying attention to it, you'll be amazed at how often it gets slipped seamlessly yet completely unjustifiably into a conversation.

      1. Terry 6 Silver badge

        "Just". Not just an IT thing.

        Anyone who says "just do.." hasn't thought through/traced the consequences. No job, however small can be guaranteed free of unexpected complications.

        As in, "You can just move the shed to that side of the garden" . Which is when you find that under the shed there was a two foot deep pit, the base of the shed is rotten and the other side of the garden is rather less even than it looked..

        Or " You don't need an electrician. Just replace that electrical socket". Fine, until you find that behind the socket there's a tangle of wires that are somehow, just, hanging into the back, but will never go back in again once moved. (I'm not an electrician, I have changed sockets, but I do know a good one to call if I have any doubts whatsoever. And I do).

        1. Alan Brown Silver badge

          Just do it

          Or " You don't need an electrician. Just replace that electrical socket".

          In many countries it's a criminal offence to do that for "hire or reward" if you don't have the appropriate pieces of paper - so having the order in writing is absolutely critical to ensure shit doesn't flow downhill.

      2. Uncle Slacky Silver badge
        Trollface

        > "Just delete the organisation" or "Just upgrade the entire domain" or "Just format the entire drive"

        Or indeed "Just leave the EU"...

    5. Anonymous Coward
      Anonymous Coward

      incorrectly removed exchange servers stick around like sh1t to a blanket in AD. Do it properly or not at all! But the trouble is when the sh1t is hitting the fan people do things in haste, they don't do restores properly etc, things then get nasty in AD!

  6. Aladdin Sane

    Howard

    is a dick.

    I hope he stuck around to sort out the mess he created.

    1. Gene Cash Silver badge

      Re: Howard

      Well, I'm sure he wasn't able to make the deposit he needed to do, so it seems to be kind of an own-goal there.

      I expect making tellers/retail clerks pissed off will be its own karma, as I find that making them happy reaps rewards for several years down the road. I've been given free lattes and such, months after helping someone get the job done in a broken situation.

      1. Waseem Alkurdi

        Re: Howard

        And why do tellers have the ability to bring down a whole system? No permission control?

        1. Killfalcon Silver badge

          Re: Howard

          "And why do tellers have the ability to bring down a whole system? No permission control?"

          Either the architect in 198X didn't think it's would come up (seriously, just don't tell them the command exists, they'll never type that by accident, right), or they did and their manager said "we don't have a week for you to code in permissions".

          A lot of what we now see as obvious best practice was learned the hard way.

          1. Alan Brown Silver badge

            Re: Howard

            "A lot of what we now see as obvious best practice was learned the hard way."

            Things such as "don't launch those solid boosters in freezing conditions" spring to mind.

            Unfortunately despite repeated warnings about stuff which seems obvious in hindsight, 'obvious best practice' is often scorned as "too difficult" or "unfeasible" until after a lot of damage has occurred - and even then you'll find someone who thinks it's too much effort.

    2. tim 13

      Re: Howard

      Who is Howard?

      1. Anonymous South African Coward Bronze badge

        Re: Howard

        Who is Howard?

        Ask Taneleer Tivan.

      2. Mark 85

        Re: Howard

        Who is Howard?

        A duck.

  7. Anonymous Coward
    Anonymous Coward

    Never burn your bridges. It may commit you to a battle you would have preferred not to fight.

    You can never step in the same river twice. No matter how familiar a problem appears - there are possibly several root causes that can give the same apparent symptom.

    1. Anonymous Coward
      Anonymous Coward

      Anecdotally, I burn any bridge that I never intend to set foot on ever again, and never want anyone else to, and which I'm totally in a position to do that without negative consequence.

      For example, if leaving a job that you so desperately detest because of serious issues with the way they deal with people... burn the bridge. You will never want to work for / with those people ever again, no matter where they may appear in your life.

      "He might be the interviewer on a future job"? Good. Then the second we see each other (or each other's name), we can nope the hell out of there and save both our time, effort and money on anything further.

      Merely don't burn your bridges WITHOUT CHECKING FIRST. The same way that you wouldn't delete a backup, or pop out a hard drive from a machine, or power off a server, before checking that you had, in fact, got the right on.

  8. This post has been deleted by its author

    1. Waseem Alkurdi

      Re: Exam question.

      That's why I always read exams to the end and solve them from end to beginning, no matter what the subject is. ^_^

    2. magickmark
      Facepalm

      Re: Exam question.

      You beat me to it!!

      I had exactly the same paper on a course many years ago when I were a lad and new to IT/Training/Support.

      Hate to say it but I was the only person in the class of about 10 or so who did actually read it all the way through.

      The other fun exercise we did was trying to tell someone how to strike a match from a closed box on a table between us with the person striking the match only doing exactly what you told them. And of course the instructor on the course had ensured that every box was upside down!!

      1. Giovani Tapini

        Re: Exam question.

        I was given a test with 100 questions on it, where the last one said, all you needed to do was fill in your name and hand it straight back. Many people were still working through it an hour later...The tutor thought the whole process was hilarious.

        1. tim 13

          Re: Exam question.

          I had a test like this. l naturally I didn't read all the way through. When the teacher asked why we had done all the questions, I said that I had read them all through, then done them in order. She didn't have an answer for that.

      2. Lee D Silver badge

        Re: Exam question.

        I know a secondary school science teacher who has literally encountered dozens of pupils who have no idea how a match works or how to light them and are shocked that it's actually a real flame that burns their fingers.

        In one way, I see that as progress (kids aren't exposed to people smoking), in another way, it is quite worrying that they don't understand how something quite basic works.

    3. Stevie

      Re: Exam question.

      Many years ago, in the last-but-three decade of the last century, a colleague told me of a Systems Analysis course he had attended at ICL.

      Everyone sat around a big table. The presenter dumped a huge box of mixed bolts on the table and said "sort that out".

      After an hour or so, when the bolts were sorted in order, he said "Well done". Then he picked up the single four-inch carriage bolt sitting on it's lonesome at one end of the collection. "But I only wanted this one".

      The lesson being that the course was going to be all about discovering the right questions to ask when given a user request.

      I believe the Systems Analyst job position has largely died out. A shame. Many of the issues we read of here at El Reg have to do with not asking the right questions.

      Scope creep is a whole 'nother issue and has bee with us since Gak Eisenberg demonstrated his perfectly fit-for-purpose hammerstone to the tribal elder and was asked if he could add an antler handle to it and maybe use a more glittery rock.

      1. doublelayer Silver badge

        Re: Exam question.

        To some extent, that's true. Still, there are situations where you can't get people to tell you why you're doing something. It's entirely logical, if told to sort a box of bolts, to do so. After all, if the person telling you to do that just wanted the biggest one, they could either have taken it out at the beginning or asked you to find one with the required specifications.

        Sometimes, you want someone to just do what you ask of them rather than to believe they can do it better if only they know everything there is to know about what you're doing. For example, if I ask someone to find the most cost-efficient machine with a set of specifications, I only want them to look at the options, eliminate those that have worse specifications, and choose the one that has the lowest cost (perhaps taking into account other things that they can definitely ask me to elucidate). I do not need them to question me as to whether I want more power because they found one that's only a little more expensive, nor do I need them to suggest that we'd probably be fine if we bought machines with less memory. I set forth the specifications and gave them a task. If they're going to change the task instead of just doing it, perhaps they should be doing my job.

        The same is true of software jobs. I cannot deal with every part of a project team thinking they can and should be designing a better system for every component. Their system for some of it may in fact be better than the one we're using, but if it doesn't integrate and won't without doing a lot of work first, it can still be worse. And if each team or team member comes up with their own version that doesn't interact, we spend forever getting things back together. That's why abstraction is so key; figure out the best way to do your job, not the best way for someone else to do theirs or even for you to do someone else's job. If you have some improvements to suggest, go ahead, but don't neglect what you're supposed to be doing just because you don't like someone else's work.

  9. msage

    Caution

    I agree with the comments here although I have worked with fellow techies take things way to far in the caution direction leading to nothing getting done and being stuck in a perpetual risk / change loop. While things should be planned, risk is not the reason to not do something.

    If you don't do something, you end up with systems that are 10-15 years old because they just run and you run out of support. Then you have major upgrade issues as most of the time you have to step upgrade to versions that also aren't supported.

    In my mind it is all about balance.

    1. PickledAardvark

      Re: Caution

      "If you don't do something, you end up with systems that are 10-15 years old because they just run and you run out of support."

      The roles of managers are to keep the stuff created in-house up to date and to keep the out-of-house stuff within bounds of support. If managers aren't doing that, you are in a problem organisation. Companies can run ancient systems for years -- as long as they are properly managed.

      It is unlikely that any of your positive actions -- at sys admin level -- will change organisational direction unless a manager is on your side. But they might be the right things to do.

  10. nil0

    Cut the red wire

    but not before you've cut the blue wire.

    1. Rich 11

      Re: Cut the red wire

      ...and not before you've evacuated the building rather than your bowels.

    2. usbac Silver badge

      Re: Cut the red wire

      Like this:

      https://www.youtube.com/watch?v=UcaWQZlPXgQ

      Bruce

  11. Tom Melly

    Reminds me of a recipe...

    ... that helpfully mentioned at the very end that you should add two tablespoons of chopped thyme halfway through cooking...

    1. Anonymous Coward
      Anonymous Coward

      Re: Reminds me of a recipe...

      Exactly, that annoys me too. Especially the ones that say in the middle "Leave overnight in the refrigerator."

      It seems to be the root cause analysis here is a badly worded document. It should start "This only applies if you have a single Exchange server. Other requirements before proceeding are..."

      I used to tell our PHB that I could NOT write training manuals because I knew how the software worked. Technical authors are really needed.

      1. Aladdin Sane

        Re: Reminds me of a recipe...

        Whenever I write process docs I get people who don't know what I do to check them.

        1. Robert Carnegie Silver badge

          " I get people who don't know what I do to check my documentation."

          Interesting. What do you do? Although I think you want to impress us with what you know. ;-)

          If people don't know what you do, won't your documentation tell them what you do? Or is that what you're trying to confirm?

          1. Is It Me

            Re: " I get people who don't know what I do to check my documentation."

            I find starting with a list of prerequisites can work well.

            And even who the document is aimed at, so people can judge if it is something they might want to escalate rather than attempt themselves.

      2. Anonymous Coward
        Anonymous Coward

        Re: Reminds me of a recipe...

        I used to tell our PHB that I could NOT write training manuals because I knew how the software worked.

        If I had £1 for all the managers who didn't listen when I told them that I could not test this piece of code because I was the one who wrote it, I'd be able to employ someone full time just to empty the ashtray in my other Lamborghini.

  12. PickledAardvark

    If...Then...Else

    My documentation explained that an automated process would clean up some artefacts from the installation process within 15 minutes. The artefacts were harmless but annoying. Users didn't see them. I was cleaning up because I am conscientious. And you have other things to do on the PC which take more than 15 minutes.

    My documentation explained that IF the process didn't clean up (2% failure rate), THEN the next run would do it. Or the one after that. ELSE that fails too or you are in a hurry, in which case you can delete the files manually.

    So why are you on the phone after 16 minutes asking what to do?

    1. DropBear

      Re: If...Then...Else

      Because that's the kind of instruction that never fails to confuse its audience. First they get "you don't need to" followed by "but you can if you want" and that invariably results in "now should I or should I not?" - I'm pretty sure the syndrome even has a name but I can't recall it. I do understand that this is technically not a fault in the instructions themselves which merely go to out of their way to fully describe all possible options and possibilities, but the fact remains their effect on the user is to cause confusion and paralysis unless said user is unusually adept at this sort of thing. Which is exactly what one should not and can not ever safely assume.

      1. PickledAardvark

        Re: If...Then...Else

        "Because that's the kind of instruction that never fails to confuse its audience. First they get "you don't need to" followed by "but you can if you want" and that invariably results in "now should I or should I not?"

        IF

        THEN

        ELSE

        IF my audience doesn't comprehend THEN my audience has failed computer logic, and we need a chat.

        I don't like bossing people around.

  13. Giovani Tapini

    Trusting advice on the internet...

    Anyone that trusts what the internet says blindly is, frankly, asking for trouble.

    Even technical advice for problem solving, although often helpful, is often resolving a problem that is only "similar" and therefore the solution may either be ineffective or add to the problems you have.

    I rarely find advice that directly matches the situation I encounter, or relates to the same combination of software versions I am running.

    Unless what you read is close to, aha, I would have thought of that eventually, you may want to get a second opinion...

    Outside the techie world there is a great deal of "advice" which is positively malicious too, and plays the gullible to brick their devices, and remove their data...

    1. Rich 11

      Re: Trusting advice on the internet...

      Anyone that trusts what the internet says blindly is, frankly, asking for trouble.

      Some years ago my dad, approaching the end of his life, thought it would be a good idea to write down all he could remember about his side of the family, annotate old photographs, family collections, etc. I helped him draw up a family tree and organised a mostly-sufficient filing system for his notes. One day he read an article about genealogy software, so he called me and I bought a subscription to one of the more widely recommended services, installed the software on my laptop and took it along next time I went to stay with him. We spent a couple of days doing all the research we could, trying to clarify names and dates and places and match them up. All of a sudden it fitted together and we were able to slot in about six generations from the late 18th to early 20th century, about 80 years further back than the oldest surviving photo or letter. We were well chuffed with ourselves.

      But something didn't feel right about two connections in the 1880s and 1890s. It took a while, but we eventually got to the bottom of it. One of my cousins had researched the family a few years before, and it turns out she'd made a mistake with those two connections, linking us to a family who just happened to live in the same area (but one census apart) and have two eldest children with the same comparatively uncommon first name as a great-aunt and great-uncle my dad could remember from his childhood (our surname is reasonably common in that area). The software had found my cousin's work in one of the databases it monitored and from then on effectively presented it as verified.

  14. J.G.Harston Silver badge

    Cleaning a laser printer

    Early 1990s.

    "Open lid, remove toner cartidge, remove charge transfer drum (see diagram)"

    Ok... done that. Turns page.

    "Under no circumstances do this in exposed light"

    1. Aladdin Sane

      Re: Cleaning a laser printer

      Always read instructions top to bottom before starting step 1.

  15. steviebuk Silver badge

    I can't stand guides...

    ...where the engineer has "assumed" knowledge but not mentioned this. I understand sometimes you have to assume knowledge, but fing put that at the beginning. Don't skip steps that you "assume" a person that's never seen the guide before, for software they've never seen before, will "work it out".

    That's why I like to do my guides as if you've never done it before. You know IT but you've never followed this guide before. I put every single annoying step.

    The most false guides I've seen are in gaming when in the chat window. Back in the Vietcong days, if people had issues and asked in the chat. You'd get several knobs telling them to do "Alt F4. That will fix your issue".

    Cocks.

    1. Anonymous Coward
      Anonymous Coward

      Re: I can't stand guides...

      Haynes car maintenance manuals were fond of a step "remove ...." - without the essential details of how the thing is held together.

      The Haynes Series "A" Range Rover manual simply said "remove back seat cushion". After much struggling it was lifted out - with a now bent flange that required the cushion being slid outwards to disengage it first.

  16. Anonymous Coward
    Anonymous Coward

    Warnings and prep at the top!

    I write technical instructions as part of my job. I have a standard outline for all of them:

    1. Safety permits, etc. needed

    2. Notes on safety hazards and how to mitigate them.

    3. Equipment and tools needed (aside from standard hand tools)

    4. Actual procedure

    The procedure section frequently starts with "Schedule work with affected department" or similar statements. Any important note about what NOT to do is on its own line, at the appropriate point in the procedure, with the word NOTE: (or occasionally something stronger) in front of it.

    Write your procedures so that a brand new employee can follow them!

    1. The Oncoming Scorn Silver badge
      Coat

      Re: Warnings and prep at the top!

      The document that got 2/3rds of the way through post image setup of a server, then presented a screenshot of "Continue..... " "Yes" "No", at the very bottom of the page then had 2.5 of blank pages before it resumed with " graphic of a stop sign & text saying STOP - Do Not Press Yes At This Time".

      By which time it was too late & you had to reimage the new bank server at 12.30am all over again.

  17. NXM Silver badge

    Mini brakes

    Fixing a leaky master cylinder I followed the instructions in the Haynes manual to remove it, then got to where it said "using a pair of circlip pliers....". Did I have a pair of circlip pliers? No, I did not.

    I had to put it all back together, drive to the shops and buy some, go home and dismantle it all again. Bugger.

    1. TRT Silver badge

      Re: Mini brakes

      And this is why we have the bits no-one ever reads:

      System Requisites and Required Tools.

      1. DuchessofDukeStreet
        Facepalm

        Re: Mini brakes

        Those bits are in the templates I have to use for the most irritating and inefficient process ever - and you're the first person who's ever explained *why* they're there...

        I really am an idiot sometimes.

    2. Anonymous Coward
      Anonymous Coward

      Re: Mini brakes

      "circlip pliers"

      IIRC which can come in two varieties depending on whether you need to expand or contract the circlip to fit it in place.

      1. PickledAardvark

        Re: Mini brakes

        "IIRC which can come in two varieties depending on whether you need to expand or contract the circlip to fit it in place."

        In the application of a mini brake cylinder (not a master cylinder which is bolted to the bulkhead), a slave brake cylinder retainer clip clip should be removed by a blunt-ish screwdriver. Maybe by needle nose pliers. Not your decent screwdriver for obvious reasons.

    3. Insert sadsack pun here

      Re: Mini brakes

      Haynes manuals were also notorious for the whole second half of the job being summarised in the last step: "assembly is the reverse of disassembly", no matter how complicated the first half was. Thanks a bunch!

  18. dajames

    When I was about 12 my parents bought me a cheap tape recorder for my birthday (this was a couple of years before cassette recorders became ubiquitous, so it was a bit of a rarity). I bounced down to breakfast to find the gadget positioned beside my place at table, not wrapped or even in its box, but with the instruction booklet on top.

    Wasting barely a moment on the Book of Words I pressed the "Play" button and my father's voice emerged from the small loudspeaker saying:

    Read the Instructions FIRST!

  19. ma1010
    Mushroom

    Steps out of order

    Obviously, the article should have had the bit about "Only do this is you have only one Exchange server" at the beginning.

    This reminds me of the old joke about the guys disarming a bomb with one guy reading the instructions to the other.

    "Unscrew the cover!" "Okay, got it unscrewed."

    "Cut the red wire!" "All right, I've cut the red wire. What next?"

    "But first, cut the blue wire..."

    ------------------------------> See Icon

    1. Anonymous Coward
      Anonymous Coward

      Re: Steps out of order

      Post the joke.

      But not before reading the thread to make sure it hasn't already been posted.

  20. Stevie

    Bah!

    I recently pulled an Old Man Idiocy when using TOAD (an excellent tool, but like all tools very dangerous in the hands of the unknowlegeable, forgetful or just plain lazy - last one applies in this case).

    Asked to move an Oracle package from a test database schema into our production schema I proceeded to pull up the package in TOAD, did a create script to the clipboard, pasted it into the editor window in the target database session, edited the code to change the schema name and ran said code in the production database that night as requested.

    Next day no-one could access the package code. It seems some witless dolt had removed all the permission grants and synonyms from the package.

    Turns out I had neglected to double check the check-boxes on tab in the create script pop-up that controls the generated code closely enough, and had neglected to notice that the generated code contained the dreaded "drop object" syntax.

    Not only that, I had neglected to recognize that that had happened when I did the code edit for schema name change. I mean, it was only hiding in plain sight on bloody line one.

    Unfortunately, I rather like all the people I work with now, so I was forced to do the Bonehead Dance and wear the Pointy Hat of Not Being Smart instead of shifting blame to the intern or new hire as per industry standard practice.

    D'oh!

  21. Alan Brown Silver badge

    Ah, american documentation

    "And that I learned always read an article to the end before implementing the procedure."

    Yup. ESPECIALLY if said documentation originates from the USA, where the important bits are almost always at the end.

    EG: technical procedures for adjusting Harris 15kW shortwave transmitters. When you get to step 23 they tell you 5 steps you should have undertaken before step 1, 3 more before step 6 and helpfully inform you that if you haven't done these and taken 6 crucial measurements before step 3, you'll need a vector analyser to recover.

  22. raving angry loony
    Thumb Up

    Learn from your most pedantic profs

    The one thing I learned from my most pedantic, most arsehole, most annoying, most fucking terrifying profs was "READ TO THE END OF THE INSTRUCTIONS. DAMNIT!". There is a reason those fucking goatfucking twats write exams that start "read to the end" and end with "only do question 1, which is "write your name"". That's exactly to avoid situations like this. Those profs were attempting to impart a lifetime of knowledge in an all too short timeframe. As Stargate taught us, the young do not always do at they are told. Learn from this.

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