back to article You need to RTFM, but feel free to use your brain too

Monday is here, and with it a warning that steadfast determination to ignore instructions might not be such a silly thing after all. Welcome to Who, Me? Today's story comes from a reader Regomized as "Sam" and takes us back to his first proper IT job following his departure from the education system. Sam found himself on the …

  1. Pascal Monett Silver badge
    Trollface

    Nice one

    Last week I commented that the Who Me? character didn't have procedures to follow.

    This week you give me case where the procedure was followed to the letter.

    I'm sure you did that on purpose ):D

  2. J.G.Harston Silver badge

    Well, he had not been told anything about shutting down the system, and the documentation for 'reload' didn't mention anything about shutting down the system. Fault in the documentation, not with Sam.

    I've (re)written loads of procedures like this, and specifically include such "common sense" instructions specifically because if you're coming with no prior knowledge, then it isn't common sense. Some even start with "remove equipment from box".

    I remember this biting me way back in the early 1990s. Cleaning the drum(?) in a laser printer. I followed the instructions in the documentation.Took shiney rolly bit out, put it to one side. Read next paragraph, start digging into printer to remove next part. Mini-boss came past: DON'T EXPOSE THAT TO LIGHT! IT WILL DESTROY IT!!!! covering it with a towel. Me: How would I know that? Where does it say it???? There's no warning. Flips over two or three pages, and there it is.

    1. Roger Lipscombe

      Dr. Stephen Strange : Yeah, you know, you really should have stolen the whole book because the warnings... The warnings come *after* the spells.

      1. Eclectic Man Silver badge

        re: preparation

        The composer Edward Elgar was going though one of his compositions with a student who complained that there was a part for the clarinet while the rest of the orchestra were playing quite loudly and the clarinet part was soft and no one would be able to hear it. Elgar responded by pointing out that over the page the clarinet has a solo and he thought the player might like to get warmed up.

    2. TonyJ Silver badge

      I once did a set of documentation to install and configure an Altiris solution.

      I've always prided myself in always assuming that the reader of such documents may be coming at it with zero knowledge and try to avoid skipping steps because they are obvious to me. So mine would be down to a screen shot with which button to press, what text to type etc - always with a bright red box around the relevant part of the screen shot.

      During the development of the build, I was being shadowed by an ex-Royal Navy chap who was brand new to IT. One of his jobs was to go through the documentation to ensure it was up to muster.

      The next thing I know I am dragged into an "urgent" meeting with the programme lead because the test was an unmitigated disaster and the chap's response was "Don't blame me - I followed Tony's document".

      Only he hadn't. It was clear from 30s of basic tests that he'd skipped over entire sections because he "thought he knew it and didn't look at the document for that part". He then doubled down and took humbridge when it was pointed out that he was there to test the document, not his personal knowledge which he'd only proved to us was lacking.

      The next time he ran through it, I made him tick every section to prove he had read it as well as shadowing him to ensure he was actually following the document. And to no one's surprise it ran exactly as expected.

      TL/DR - never assume the person reading your document has any knowledge of the system they are looking at.

      1. Sam not the Viking Silver badge

        Based upon personal experience....

        Just a point to note, I'm sure it will ring bells....

        When writing the detailed steps, never, ever, ever, put more than one instruction on a line.

        I have wasted more time than I care to admit trying to figure out what I am doing wrong when following the procedure 'exactly'. So I thought.

        Nothing is foolproof because fools are so clever.

        1. Anonymous Coward
          Anonymous Coward

          Re: Based upon personal experience....

          "When writing the detailed steps, never, ever, ever, put more than one instruction on a line."

          This only applies IF you do not read the instructions BUT skim the instructions and ASSUME the end of the sentence(s).

          Place at the top of every page the following:

          PLEASE READ ALL THE WORDS IN THE INSTRUCTIONS ... DO NOT SKIM & ASSUME !!!

          P.S.

          Nothing is foolproof because there are so many fools .... and they outnumber us more & more each day !!!

          :)

          1. yetanotheraoc Silver badge

            Re: Based upon personal experience....

            "they outnumber us more & more each day !!!"

            I used to be the smartest person on the planet. Anybody who disagreed with me was clearly deluded. Now I've demoted myself to the B team, and I can confidently say I'm the smartest person on the B team. Er, what were we talking about?

            1. Anonymous Coward
              Anonymous Coward

              Re: Based upon personal experience....

              Mea Culpa.

              Implied correction accepted !!! :)

              We are all 'Experts' when one references their own personal 'Knowledge Domain' & 'Fools' when referenceing someone elses to varying degrees of 'Foolishness'. !!!

              1. Montreal Sean

                Re: Based upon personal experience....

                I'm not even sure I'm an expert when it comes to my own personal "knowledge domain".

          2. ITMA Bronze badge
            Devil

            Re: Based upon personal experience....

            Now there is your problem right there:

            "PLEASE READ ALL THE WORDS..."

            You're assuming that they CAN read and aren't just looking at the pictures...

            1. Rich 11 Silver badge

              Minor qualification

              "PLEASE READ ALL THE WORDS..."

              "...IN THE RIGHT ORDER."

              1. Strahd Ivarius Silver badge

                Re: Minor qualification

                No, the other right!

          3. John Brown (no body) Silver badge
            Joke

            Re: Based upon personal experience....

            "PLEASE READ ALL THE WORDS IN THE INSTRUCTIONS "

            Sorry, I stopped reading there and looked at the pretty picture, then forgot what the words said. I was brought up on IKEA-style instructions.

            1. ITMA Bronze badge
              Joke

              Re: Based upon personal experience....

              "I was brought up on IKEA-style instructions"

              That might explain why you have 3 keys caps spare and two holes with no keys in them....

          4. Intractable Potsherd

            Re: Based upon personal experience....

            "Place at the top of every page the following:..."

            I have a strange sort of word-blindness - anything like a title or a header very rarely registers with my consciousness, especially if it is in a different font or colour without underlining. Underlining says to my brain "this is important", but boxes not so much.

        2. Anonymous Coward
          Anonymous Coward

          Re: Based upon personal experience....

          Or leave large spaces between the command and the options......

          Anyway, my colleague decided that, despite me using a different font, different colour and on a separate line, that he didn't need to type the options that followed the command.

          * can't remember what, too many years ago, still not a Linux person - I did a guide for setting up a Linux box with commands for kernel linking stuff and copying files across for an Adaptec SCSI card etc. (I had two boxes to set up, when I was asked how long it took - I said "Two days, 45 minutes! Two days for the first and 45 minutes for the second".)....

        3. Ian Johnston Silver badge

          Re: Based upon personal experience....

          When writing the detailed steps, never, ever, ever, put more than one instruction on a line.

          And also make sure that after every instruction you include a clear description of the expected results.

          1. stiine Silver badge
            Happy

            Re: Based upon personal experience....

            I've you're like me....you also include several examples of what to expect when you do it wrong and tell you how far back up the instructions you have to go to recover.

            When I'm writing instructions, I always document the steps as I'm, for example building a new application server, performing them. Then I delete the VM and start over by following the instructions. When the instructions are complete, I do it one more time just to make sure it wasn't a fluke.

        4. fidodogbreath Silver badge

          Re: Based upon personal experience....

          Nothing is foolproof because fools are so clever.

          They can also be extremely persistent. "If at first you don't fail, try, try again."

        5. Anonymous Coward
          Anonymous Coward

          Re: Based upon personal experience....

          Likewise, make sure that each instruction is entirely on one line. There's a set of instructions at $work with a line broken up because of a linewrap:

          cp /someCrazyLong/pathName/"ending up at a bizzare; filename"

          /then-a-pretty-long-destination-too

          The *THIRD* time I followed the instructions, I remembered that this command had a linewrap in it and did it right the first time. (First two times I saw the error that was returned and retyped it correctly.)

          And yes, there's a semicolon in the filename to copy, with quotes just around the filename.

        6. ITMA Bronze badge
          Devil

          Re: Based upon personal experience....

          "Nothing is foolproof because fools are so clever"..

          You can make things foolproof. What you can't do is make them people proof.

        7. pirxhh
          Holmes

          ASD-STE100

          The flyboys have found that operating and maintenance procedures are quite important to ensure that things stay up until the pilot wants them to come down, preferably in one piece and at an airport.

          So they developed Simplified Technical English.

          When I write procedures, I follow that at least in spirit if not in letter. It contains so useful rules as to always call a spade a spade, not a shovel and a manually operated earth-moving device or MOEMD in the next paragraph. And use numbered lists for steps where order matters, bullets otherwise. And simple sentences ("Do ...") in active voice.

          Everyone writing instructions should at least read it, it's free.

          1. Jou (Mxyzptlk) Silver badge

            Re: ASD-STE100

            > Everyone writing instructions should at least read it, it's free.

            It costs time to read. Therefore is it not free.

          2. mdubash

            Re: ASD-STE100

            Consistent naming is a real problem.

            Vendors are the worst for renaming technologies in order to claim them. When I was starting out in tech journalism, it drove me crazy chasing down various definitions only to find they all meant the same thing.

            But it seems that many (most?) people who write stuff, instructions or not, don't think about the confusion they cause. I call it write-only writing.

      2. Anonymous Coward
        Anonymous Coward

        Zero Knowledge

        I work for a company where the "Global Senior Director of Quality" (whose reach is not global) prided himself on hiring his buddies from his previous job where none of them have any relevant knowledge of our Industry much less the Technology of our industry. (Akin to hiring dairy farmer milk QA folks in a SpaceX factory.) Furthermore, his philosophy is to not have his people contaminated by any relevant knowledge, so even after years on the jobs, none of them have picked up anything.

        The CEO was touring the factory one day, and this "Global Senior Director of Quality" was touting his QA & incoming inspection programs and the CEO stopped and simply asked, "If these programs are so good, how come 30% of our products coming off the line don't work due to faulty parts and have to be reworked?" Crickets chirped. Unfortunately, this clown is still "Global Senior Director of Quality". His boss, the GM, was fired.

        We still have to rework 30% of the products coming off the line.

        1. Kevin Johnston

          Re: Zero Knowledge

          I worked in a flight simulator company for a while and they had won the contract for a C130 simulator. A lot of very detailed work goes into these and when the chief test pilot from Lockheed came over to check it people were understandably nervous.

          He sat in the seat and ran through his checks but in almost no time he stood up and announced the overhead panel was incorrectly placed . Cue headless chickens as panic ensued until the drawings were produced which showed we had followed the Lockheed dimensions perfectly...if we had only known that when the real thing was built they move the panel a little to the left for some obscure reason and nobody had seen fit to update the drawings.

          1. Eclectic Man Silver badge
            Facepalm

            Re: Zero Knowledge

            In the movie 'Dr. Strangelove', the inside to the USA's TOP SECRET nuclear bomber was duplicated exactly. So when the showed a preview to the DoD's top brass, they were told A) You cannot show that it is TOP SECRET, and B) You guys had better have a VERY good explanation for how you got that information.

            Outside they had lined up all of the documentation showing how they had got it all from published articles in Flight, Aviation Week, newspapers, magazines, publicity material, recruitment documentation etc.

            https://en.wikipedia.org/wiki/Dr._Strangelove

            1. mhoulden

              Re: Zero Knowledge

              In the days before the UK had a Freedom of Information Act someone asked the local police force for details of their internal computer systems. They refused. However all the details were available in a job advert that anyone could ask for.

            2. Antron Argaiv Silver badge

              Re: Zero Knowledge

              Aviation Week, aka Aviation Leak.

              They are very good. A previous employer had a subscription, because the CEO was an airplane buff.

            3. Robert Carnegie Silver badge

              Re: Zero Knowledge

              A comma or stop wanted? i.e. "You cannot show that. It is TOP SECRET."

        2. John Brown (no body) Silver badge

          Re: Zero Knowledge

          "We still have to rework 30% of the products coming off the line."

          Clearly the quality control is working and consistent. What? You thought QA was there to make changes? That's engineering's job.

      3. An_Old_Dog Bronze badge
        Gimp

        Documents for Robots?

        If one were to write documents for robots, rather than for thinking, at-least-somewhat-knowledgable humans, they would be extremely long. Is your company employing robots for its IT staff?

        To prevent oopsies of the "I didn't know, the doc didn't say 'X'" type, the docs I write state up-front the expected knowledge-level presumed by the document, and state the presumed pre-conditions (system running, system powered-off, etc.) These are clues to thinking humans that they might have to reference other documents (powering-down, powering-up, etc.)

        To prevent oopsies of the "I guess I skipped a step" type, I use square brackets in the docs I write; these square brackets form convenient tick-off boxes in front of each step.

      4. TeeCee Gold badge
        Meh

        Aha! You made the other fatal assumption with documentation.

        You assumed that the person running the procedure would actually read it.

    3. Wally Dug

      Documentation

      When I write documentation, I always write it "for anyone who understands IT" rather than someone whose job it is on a day-to-day basis. And every so often, I will revise the documentation, regardless of whether or not the system/process has been updated, even following the examples (which are commonly of the copy out the document and paste into the command line variety) to ensure that they are accurate, complete and easy to understand.

      And don't worry, permissions and access control means that only relevant people can do what the documentation suggests!

      It's also a good idea to watch someone follow your documentation as it's amazing how easy it is for the writer to take something for granted - start <application> and enter the following... only for the user to say "Where's <application>?"

      1. Doctor Syntax Silver badge

        Re: Documentation

        It's not just separate instructions that need to be tested this way. I've encountered so many web sites where I feel the developer should have shadowed a user in this way. And then started again and written it properly this time (subject, of course, to repeating shadowing a user).

      2. UCAP Silver badge

        Re: Documentation

        When I write documentation, I always write it "for anyone who understands IT" rather than someone whose job it is on a day-to-day basis

        When I write documentation I always include a section that details the what knowledge the person should have in order to successfully follow the instructions. There have been times when I have been asked to write documentation for an "expert" user, only to have it handed to a newbie. Having a statement along the lines of "you should know X, Y and Z, and have completed A, B and C courses" has save my backside several times.

        Oh, yes, I also include a list of tasks that should have been successfully completed before this done, along with any other pre- and post-conditions associated with the task.

        The basic rule I work to: "If it is not written down then it does not exist".

        1. yetanotheraoc Silver badge

          Re: Documentation

          "There have been times when I have been asked to write documentation for an "expert" user, only to have it handed to a newbie."

          Newbies cost less, don'tcha know? It's cost cutting 101. Management will always hand the documentation to a user less experienced than the one it was written for.

        2. Anonymous Coward
          Anonymous Coward

          Re: Documentation

          I had a colleague apply for a course covering a new bit of kit only for HR to be reject it as he hadn't 'done the basic course'.

          He duly applied for the basic course only for that to be rejected as he was too experienced (5+ years on the same job)!

          It did take a bit of toing-and-froing before a senior manager finally stepped in and gave HR a bolloxing for not spotting the obvious exemption

          1. pirxhh

            Re: Courses

            I have to complete a bunch of online courses whenever I need to go on an offshore unit (aka drilling rig).

            Including one actually written by yours truly.

      3. Alumoi Silver badge

        Re: Documentation

        Press any key to continue?

        1. ITMA Bronze badge
          Devil

          Re: Documentation

          "Press any key to continue?"

          NO!!! Not the bloody RESET/ABORT key!!!

      4. TooOldForThisSh*t

        Re: Documentation

        Long ago I was responsible for 150+ file & print servers in remote sales offices across the USA and Canada. As part of my job I provided instructions for the local LAN admins for any and all updates, fixes and procedures. I remember one call in particular from a remote site that my VERY carefully tested instructions did not work. After careful troubleshooting and double checking, his comment was "I don't have time to read those long instructions". Needless to say it worked when he did.

        1. A.P. Veening Silver badge

          Re: Documentation

          "I don't have time to read those long instructions"

          You wasted more of my time (and your own) than if you had just read those instructions!

          1. Arthur the cat Silver badge
            Facepalm

            Re: Documentation

            "I don't have time to read those long instructions"

            You wasted more of my time (and your own) than if you had just read those instructions!

            Generalised as the typical manager's excuse: I'm too busy to learn how to use the computer properly.

            Sadly the more senior the manager the less you can do about it.

            1. Terry 6 Silver badge

              Re: Documentation

              Never mind the computer. This is so much the default behaviour of a certain type of manager. S/he is too busy to learn how to do stuff that will make them less busy. But it's totally built on bolstering their own self-imprtance, of course.

            2. mdubash

              Re: Documentation

              Sadly, not just managers. Lost count of the number of times I've shown people that crtl-s is way way quicker than mousing over to the File menu, dropping down to the Save option and clicking. Only to be told that they need to get the document finished by xxx time, and can't be bothered with learning new stuff. Sigh.

          2. AlbertH

            Re: Documentation

            "I don't have time to read those long instructions"

            My answer was "We don't have time to process your pay either. Goodbye!"

        2. Richard 12 Silver badge

          Re: Documentation

          "I don't have time to read those long instructions"

          You don't have enough time not to.

      5. corbpm

        Re: Documentation

        I've been asked to write documentation so a idiot could follow it, not a competent IT professional an actual Idiot (or Director).

        After the 15th rewrite with more explanations about assumed knowledge being not assumable we had.

        This is a keyboard, This is a Mouse.

        ......

        ....

        .

        .

        sudo rm -rf /

        Imagine trying to write a manual to change a hot swappable drive for a server so the cleaner could follow it, why would a cleaner ever need to be the person to swap the drive, what catastrophe is so bad that we are left with Amy from Accounts needing to swap a drive over, how does she get access to the system, leave a key for the server room under a mat for emergencies ?

        Even with trained and competent people following well written documentation we have to exhibit some common sense and domain specific knowledge, knowing when the documentation has diverged slightly from the manual (button re-labelled or option now buried on a different menu), even then we have to think. Manuals that purport to do all our thinking for us ?, disaster waiting to happen.

    4. Flocke Kroes Silver badge

      Check you can complete before you start

      I came across an amazing exam paper. It had the following instructions:

      *) Write you name in the space provided.

      *) Read the entire exam paper.

      ... various questions with space for answers ...

      *) Hand in your paper to the examiner.

      To get full marks you have to not answer any of the questions. It got me into the habit of reading to the end of the instructions before doing anything. Documentation should be written so this in not required but in the real world there is an advantage to knowing you have all the required tools to hand before you take something down for maintenance.

      1. General Purpose Silver badge

        Re: Check you can complete before you start

        That makes another nice point. In documentation (as opposed to exams), if you're telling the reader to do something that's against expectations, abnormal or downright weird, say so. You'll reassure them, carry them with you, retain their confidence in TFM, and have a much better chance of avoiding that disaster!

      2. TonyJ Silver badge

        Re: Check you can complete before you start

        Late 80's, early 90's I had an RAF recruitment test do exactly the same thing:

        READ THESE INSTRUCTIONS BEFORE ANSWERING ANY QUESTIONS:

        1 - Read the entire paper to the end before proceeding

        2 - Write your full name and the date in the boxes above

        ...

        Bottom of last page: Complete step 2 of the instructions and hand in your paper. Do not answer any other questions or write on any other part of the paper.

        1. Gomez Adams

          Re: Check you can complete before you start

          I would assert that "THESE INSTRUCTIONS" is ambiguous as it could refer to just the instructions before the the start of the questions.More instructions after the questions start could be quite rightly construed to be not part the "THESE INSTRUCTIONS" referred to.

          1. TonyJ Silver badge

            Re: Check you can complete before you start

            To be fair - it was 30+ years ago, I suspect it was more specifically worded (as in read and follow the instructions 1 and 2 below, before answering any questions) rather than "these instructions" and the failure was more my faded memory :-)

          2. ChrisC Silver badge

            Re: Check you can complete before you start

            "I would assert that "THESE INSTRUCTIONS" is ambiguous as it could refer to just the instructions before the the start of the questions."

            Isn't that the point. The obvious set of instructions at the top of the paper tell you what to do, and step 1 tells you to read the entire paper before proceeding onto step 2. On reaching the end of the paper, you find an addendum to step 1...

            It could even be suggested that the addendum at the end of the paper isn't required anyway (other than to provide the instruction for handing in the paper immediately vs sitting there twiddling your thumbs until the end of the test period), because, as written here, there's no step 3 that says "answer the following questions". Strictly speaking anyone who does start answering the questions is going off-script and doing their own thing by making an assumption as to what it is they're being asked to do based on prior experience of seeing *similar* looking papers where they did have to answer the questions.

          3. phuzz Silver badge
            Headmaster

            Re: Check you can complete before you start

            The exam was looking for people who could follow buried instructions without question. So if you're quibbling about the instructions you're not the kind of person the RAF was looking for (for this role).

        2. AdamT

          Re: Check you can complete before you start

          Ugh. I used to hate these "joke" tests that teachers (and apparently actual serious employers) would do.

          It says "_read_" these instructions. Not "_follow_" these instructions.

          So, great, I've read them and I now know there is an inconsistency in them that future instructions will contradict previous instructions. But that just means the instructions are bad/stupid. If you do what the "joke" suggests you should do then you followed the instructions out of order - which is wrong. If you follow them in order then you did some things the last instruction told you not to - which is wrong.

          Key point then is that the person/company that set the test is wrong or thinks they are a bit clever (and is wrong about that too)

          Oblig. XKCD: https://xkcd.com/169/

          1. Peter2 Silver badge

            Re: Check you can complete before you start

            . . .

            It's not a joke. It's not intended to be funny.

            This sort of test has one purpose; it's designed to filter out people who read, comprehend and follow instructions from those who ignore obvious printed operating instructions and warnings and proceed to do things "that are obvious" despite instructions specifically saying "don't do this".

            Presumably people doing things "that were obvious" had proven expensive when working with expensive and easily breakable equipment, or things like explosives.

            1. Arthur the cat Silver badge

              Re: Check you can complete before you start

              This sort of test has one purpose; it's designed to filter out people who read, comprehend and follow instructions from those who [don't]

              It's surprising how many people will reply to a job advert saying "CVs must be in PDF, no more than two pages" with a long screed in Word format. I regard that as an excellent first filter to apply before looking at anything else.

              1. This post has been deleted by its author

              2. Doctor Syntax Silver badge

                Re: Check you can complete before you start

                "no more than two pages"

                But no indication of maximum page or minimum font sizes.

                1. Arthur the cat Silver badge
                  Happy

                  Re: Check you can complete before you start

                  Q: What's the difference between an AI lacking contextual knowledge of social norms and a smartarse pedantic techie?

                  A: Very little.

            2. doublelayer Silver badge

              Re: Check you can complete before you start

              However, it structures it with an unclear warning and puts the safety instruction in the wrong place. This is along the lines of having a label on the front of the machine reading as follows:

              Follow all safety instructions at all times.

              Do not disconnect any panels unless the machine is shut down and disconnected from power.

              and another one on the back, hidden by cables, reading as follows:

              Before shutting down, open panel 5 and disable switch 2.

              Then getting annoyed at the user who performed the normal shutdown procedure without seeing the note in a place where no operating procedures should be written. Other people here have already explained how the instructions are designed in a misleading way. Basically, it's not a great test of this, as instead of checking common sense, it's checking whether they've seen this test before (I have had someone try it on me, so when it was mentioned here, I already knew the twist).

              1. ChrisC Silver badge

                Re: Check you can complete before you start

                "This is along the lines of..."

                No, because in your example the obvious instructions on the front of the machine merely instruct the user to follow all instructions, without guiding them to find the additional instructions hidden on the rear of the machine. Unless they use their initiative and go over every inch of the machine with a fine tooth comb to see if there might possibly be any other instructions listed somewhere else, then they won't find the all important one.

                In the aforementioned test, the first instruction they're given tells them EXACTLY what they need to do to pass the test - following that one simple instruction is sufficient to direct them to the additional instruction at the end of the paper. There's no ambiguity, there's no need for them to have a sufficiently evolved sense of curiosity that they go looking for something they hadn't been told was there, they just need to follow a clearly worded instruction to the letter, no diversions, no freestyling, no making stuff up as they go.

                1. doublelayer Silver badge

                  Re: Check you can complete before you start

                  The test instructions come in various forms. Some do specify to read all text on the exam before starting, but quite frequently, I've seen the test with that removed. The instruction says to follow all instructions, and the person being examined has to go find it. Every real exam puts some instructions at the beginning and then a bunch of questions. It's not unreasonable for people to assume the normal format, as they would with single instruction lists on the front of a machine.

              2. RockBurner

                Re: Check you can complete before you start

                "However, it structures it with an unclear warning and puts the safety instruction in the wrong place. This is along the lines of having a label on the front of the machine reading as follows"

                yes - it's disengenuous - but if you're a large organisation with some VERY convoluted, ancient, and unreplaceable (for various reasons) documentation in large amounts..... you want people who are prepared to be able to deal with that. Because it's cheaper and easier than replacing the documentation.

          2. yetanotheraoc Silver badge

            Re: Check you can complete before you start

            RE: "Oblig. XKCD: https://xkcd.com/169/ "

            Oh, the irony! "OK, Listen carefully." Cutting someone's arm of is a sure-fired way to make sure the other person will not hear a word you say after that.

            1. doublelayer Silver badge

              Re: Check you can complete before you start

              I see you appear to be a person unable to understand that XKCD is intended as humor. If you're going to take advice on how to handle a situation from one of the characters, picking the exclusively evil guy is probably not the best choice. The point of the strip is still valid in this situation.

              1. stiine Silver badge

                Re: Check you can complete before you start

                I disagree. If you get to pick one, then picking the obviously evil guy is definitely the way to proceed.

          3. swm Silver badge

            Re: Check you can complete before you start

            We had a professor who once gave a multiple choice exam where the correct answer to every question was 'B'. Students got worried when they discovered the pattern.

        3. David Nash Silver badge

          Re: Check you can complete before you start

          I had something like this at school. I think I was the only one to do it right. Thinking like a computer even then!

          1. Terry 6 Silver badge

            Re: Check you can complete before you start

            I was the only one to do it right.

            When almost everyone fails a test you have to assume it's the wrong kind of test. Unless it's for a very specific and rare individual.

        4. John Brown (no body) Silver badge

          Re: Check you can complete before you start

          "Complete step 2 of the instructions and hand in your paper. Do not answer any other questions or write on any other part of the paper."

          Now THAT'S more like it! In Flocke Kroes example, it was a bit ambiguous.

        5. PRR

          Re: Check you can complete before you start

          > Read the entire paper to the end

          Non-xkcd: https://fborfw.com/strip_fix/wednesday-june-30-1993/

          (Yes, re-run today, colorized, same point)

      3. disgruntled yank

        Re: Check you can complete before you start

        Saw that in sixth grade. I'd love to say it reformed me.

      4. Vincent Manis

        Re: Check you can complete before you start

        Back when I was a university teacher, I often included the instruction `Write the word OKAPI at the top of page 2 for an extra mark’ in my midterm exams. Less than half of students did this. Some who didn’t said afterwards that they had read it, but thought I was joking! Life sometimes makes me sad.

      5. 2+2=5 Silver badge
        Headmaster

        Re: Check you can complete before you start

        > *) Hand in your paper to the examiner.

        > To get full marks you have to not answer any of the questions.

        Also, to get full marks, presumably you have to ask the invigilator where the examiner might be found in order to hand it to them personally?

    5. MiguelC Silver badge

      Re: Some even start with "remove equipment from box"

      Sometimes is understanding the instructions that is lacking.

      A long time ago, in the era of 5 1/4 floppy disks, a former co-worker had some simple ones: take the disk out of its envelope, insert in in the drive and then run the program.

      He managed to pry the magnetic disk out of its casing (with great effort, I imagine) and wondered why it didn't work as intended...

      1. Korev Silver badge
        Childcatcher

        Re: Some even start with "remove equipment from box"

        I also remember how much people struggled to coordinate the Shift - Break key combination to load a programme from a floppy disc on the BBCs

        1. J.G.Harston Silver badge

          Re: Some even start with "remove equipment from box"

          And yet bizarrely, they (mostly) never managed to struggle with ! " # $ % & ' ( ) etc

          1. Missing Semicolon Silver badge

            Re: Some even start with "remove equipment from box"

            From history, but UF

        2. ITMA Bronze badge
          Devil

          Re: Some even start with "remove equipment from box"

          I had that when working for Newcastle Education Authority.

          Had several Advisory Teachers and Teacher Advisors (I never did find out what the difference is) try and tell a primary school head teacher how to do this over the phone.

          They all FAILED.

          Why? Because they assumed the head teacher knew what "Press SHIFT and BREAK" meant and repeatedly told her WHAT to do but competely FAILED to tell her HOW to do it.

          When I calmly told her "With your left hand press and hold the left shift key. Now while keeping it held down use your right hand to press and release the BREAK key. Then release the SHIFT key".

          Worked perfectly.

          What was going wrong for everyone else?

          They never anticipated that she was first of all pressing SHIFT THEN BREAK (one after the other) before being told to do them "together" at which time she was stabbing at both keys simultaneously and just happened to be releasing the SHIFT key a fraction of a second BEFORE the BREAK key. Which doesn't work.

        3. John Brown (no body) Silver badge

          Re: Some even start with "remove equipment from box"

          Ah, yes, where the "BREAK" key was most definitely not the ANY key to press to continue

      2. G.Y.

        Re: Some even start with "remove equipment from box"

        Happened when the IBM PC people were testing bit out on beginners.

        They rewrote the instructions

        1. gnasher729 Silver badge

          Re: Some even start with "remove equipment from box"

          I did write instructions once how to set up the environment for a new software developer. It assumed that you started with a Mac inside its box. And it started with the instruction to follow all instructions and produce a new setup document including all changes the had to make because the instructions were only used once a year or so.

        2. ITMA Bronze badge

          Re: Some even start with "remove equipment from box"

          Was that when they tried them on users and found the users were trying to find the ON switch on the box?

    6. Killfalcon

      One place I worked was going through a lot of workflow improvements, and was pretty good at keeping the documents up to spec, but... sometimes the document updated had a very strange idea of how linear time works, with notes *after* defunct sections.

      The worst was one where step 34 was "steps 7-33 have been automated and no longer need to be performed". It wasn't even highlighted, so it was easy to miss if you checked the docs before starting.

      Took over an hour to do those steps, too, so while I was glad to not need to do them again next quarter, it stung a bit to have wasted the time.

      1. The Oncoming Scorn Silver badge
        Facepalm

        Had a guy that left 3 or 4 paragraphs in a revised document then put underneath, "The build process has changed, these steps are no longer required".

    7. mikecoppicegreen

      There used to be a standard for writing test procedures used in part of the armed forces, and these had to be of the detail of:

      1) remove device under test from from travel case

      2) plug power lead into device

      3) plog power lead into test supply socket

      4) switch on device

      5) Connect red lead from red socket on device to red socket on test source

      6) connect black lead from black socket on device to black socket on test source

      7) ensure test source outlet switch set to zero

      8) switch on test source

      9) allow all to stabilise for 20 minutes

      10) ........

      It's mind bending to write, and even then stuff can go wrong!

      1. LogicGate

        Insufficient detail...

        5) Use a size 2 philips head screwdriver to connect red lead from red socket on device to red socket on test source. Take care not to over-torque the screw since this may lead to the brass threads in the test source being damaged.

        1. John Brown (no body) Silver badge

          5a) NO! STOP! An army boot is not a substitute for a size 2 Philips Screwdriver. Neither is whatever random screwdriver Pte Philips loans you, size 2 or otherwise.

        2. Anonymous Coward
          Anonymous Coward

          Sorry, you failed.

          "Use the POINTED END of the screwdriver..."

          1. Anonymous Coward
            Anonymous Coward

            "... to turn the screw clockwise (top of the screwdriver should go to the right)..."

            Otherwise they may just hammer the screw with the screwdriver!

            1. Terry 6 Silver badge

              Huh, you should see me trying to use a screwdriver in an unusual angle, say from underneath the object.

              I have to try it out the normal way first...

            2. John Brown (no body) Silver badge

              The top to the right? That's confusing.

              I learned many years ago that turn the screwdriver widdershins to loosen a screw and deosil to tighten a screw. Unless it's a left-hand thread. Then someone confused us all by inventing the clock!

      2. yetanotheraoc Silver badge

        even then stuff can go wrong!

        "8) switch on test source"

        If test source was already switched on, and not set to zero, then steps 5 and 6 were too early and/or step 7 was too late.

    8. HammerOn1024

      I've seen this

      This reminds me of a MASH episode where a bomb landed in the middle of the compound during the Army-Navy game. Trapper and Hawkeye were sent out to defuse the bomb while Colonel Blake read them the instructions to defuse it.

      They got to the part about cutting the wires to the fuze which Blake dutifully called out and Trapper, I think, cut. The next instruction Blake calls called out begins with "But first..." and, as you may well guess, everyone's "Ohnosecond" face came full on!

      Trapper and Hawkeye ran for it. The bomb exploded. It was a CIA propaganda bomb. Leaflets flew everywhere.

      1. LogicGate

        Re: I've seen this

        https://youtu.be/UcaWQZlPXgQ

      2. J.G.Harston Silver badge

        Re: I've seen this

        I would typically writte that as:

        Prepare to cut the blue wire

        First, blah blah blah

        Then ensure blah blah blah

        Then cut the blue wire

        1. yetanotheraoc Silver badge

          Re: I've seen this

          "Prepare to cut the blue wire"

          For a certain class of user, that's the same instruction as "Cut the blue wire".

        2. Richard 12 Silver badge

          Re: I've seen this

          Better:

          - Locate the Blue wire

          - Prepare some stuff

          - Do some nonsense

          - Cut the Blue wire

    9. Terry 6 Silver badge

      Yes, the problem with "common sense" instructions is that they may only make such sense to the individual who has an overview. To anyone simply following procedures from start to finish, if it isn't written it doesn't exist.

      In this story, to me alarm bells rang as soon as I read that he was getting out the procedures. Which meant he was being asked to perform a mission critical task he'd never previously used, without supervision, and without a read through to understand what it was all about (apparently).

      1. CuChulainn Silver badge
        Happy

        There's also the issue of not having any common sense.

        Years ago I was a passenger in a car and the driver had not long passed her test. We came to a large roundabout with multiple lanes and she began to panic.

        I tried to explain how to just stay in the lane she was in but she was still panicking, so just said 'Look. Follow that car in front'.

        We got round safely and all sorted.

        Until we turned off into a housing estate about a half a mile further on.

        I said 'What are you doing?'

        She replied 'You said to follow that car'.

        I learned two things out of that. First, common sense isn't as common as you might think, and second, that if you show someone how to turn something on, you must also teach them how to turn it off - no matter how simple the on/off control might be,

        1. yetanotheraoc Silver badge

          Next day

          She needs to get around the roundabout, so first drives to the housing estate and waits for the other car.

          1. Richard 12 Silver badge

            Ah, a mathematician

            They have reduced it to a problem that's already solved.

        2. Rob Daglish Bronze badge

          Ah... I experienced something similar with my Mrs one day. We'd been away somewhere she wasn't familiar with, so I was navigating while she drove. After a certain point on our way home, she went "Oh, I know where I am now!" so I duly stopped navigating. After she carried straight on past the junction we needed, I asked why she wasn't going the normal way home, to which she replied "oh, i know where I am, I just don't know how to get home from here!"

    10. JimboSmith Silver badge

      I wrote a set of instructions for an important procedure which would only need to be done once in a blue moon. However it would need to be done flawlessly and quickly when that time came. Not a huge company and it might happen at any time, so everyone was going to be sent a copy of these instructions just in case they were the only person there. So as you might expect, clear precise instructions were vital. I documented every step very thoroughly to make it foolproof. This included telling the user to go to security, requesting and getting the correct pass to let you into the server room if your pass didn’t normally allow you access.

      So they were written in draft form and I selected a few non tech people to follow them through. I had a duplicate system set up that they could use for the training and off we went. One of them ignored the pass section and then wondered why he couldn’t get in to the server room. Another didn’t check the status of one service before shutting it down and rebooting it. The first woman I tested followed everything precisely and every step was done correctly.

      She was a secretary/PA and always followed instructions carefully. She suggested that I write on the top in big red letters

      “Failure to follow these instructions to the letter may have an impact on your employment status.”

      That did the trick for future tests and everyone followed every step correctly.

    11. WhoAmI?

      Re: laser printer drums

      Cover it with a towel? A TOWEL!? We'd have killed for a towel in our workshop! Expenses didn't cover anything as nice as a towel. We had to make do with delicately arranged sheets of A4 paper draped over said drum and hope that no one opened a door so it all flew away. Yes, Sellotape was also a luxury

      It was great when Kyocera brought out their sapphire drums that could be left on the side for a while. So much easier

    12. DS999 Silver badge

      Writing "how to" documentation is very much like programming

      You need to specify everything exactly, in a consistent form, in the specific order necessary.

      Unfortunately people are not CPUs, and don't do exactly as told, which is why programmers hate writing documentation.

      1. Jou (Mxyzptlk) Silver badge

        Re: Writing "how to" documentation is very much like programming

        And CPUs use "out of order execution" today... If you have the money several hundred CPUs at the same time. They become more and more human.

    13. Antron Argaiv Silver badge
      Thumb Up

      Technical Writing

      When I took a tech writing course, it was mentioned that order is important and the phrase, "but first..." has no place in a procedure.

    14. John Brown (no body) Silver badge

      Some even start with "remove equipment from box"

      Up until someone breaks it by opening the box in some unorthodox way, at which point you need to explain how to open the box properly and safely :-)

    15. Plest Silver badge

      One of my favrourite expressions is "Never underestimate the ingenuity of a fool.".

      When you write documentation you must have have empathy, you must inject it at every turn. Know your audience and write to them, to the point that your declare the audience at the head of the documentation and stating that proceding further without requisite knowledge required is punishable by company discipline procedures.

      Put the fear of their chosen diety into them before they start, if they choose to go on then woe betide them, they took on the responsibility and as tech author I'm in the clear.

  3. ColinPa Silver badge

    Just following instructions

    One of my first jobs in IT (1980s) , was "application build". In those days DOS/VSE had one disk for the whole system!. Development tested on one system, I built on another system, and when the build was successful, switch disk, and re-ipl. So 2 disks in total.

    I followed the instructions "delete the libraries using the ... command". 5 minutes later my manager came round saying the live system had gone AWOL.

    I showed him the instructions and he said "ahhh. It should say use the build disk - see the white board, then delete the libraries".

    I updated the doc.

    Next week we had the same problem. My boss came in and said "you've messed it up again! Didnt you learn?" I showed him what I had done, and he said

    "Ahhh, it should say update the white board to swap the disks round, then.."

    Come the third week, I was in charge of a less critical build system.

    1. yetanotheraoc Silver badge

      Re: Just following instructions

      "Come the third week, I was in charge of a less critical build system."

      What?! In a few more weeks the instructions would have been perfect.

  4. elsergiovolador Silver badge

    Literally

    A lot of manuals are written in a way that don't consider the person reading it may be taking the instructions literally and depending on the domain knowledge of the reader some instructions may not be seen as ambiguous and that is a recipe for disaster as it will not trigger the alarm bells, that perhaps the manual shouldn't be followed that way.

    1. Ken G Bronze badge
      Angel

      Re: Literally

      I like to give my documents to someone like than and see what happens - as a quality check on me.

      1. DS999 Silver badge

        Re: Literally

        In my consulting I've often ended up writing scripts to automate certain tasks that were done by humans and thus error prone and inconsistent (or not done at all) Depending on what it is doing it may ask for various inputs, and/or produce various outputs that require further action.

        The way I test them is to find out who the manager or lead thinks are the least clueful people on the team that will be using it, and have them run it and see if the questions asked or information provided by the script can be improved based on their feedback.

        Simultaneously I have a couple people from the team who will be maintaining the script (sometimes the same team, sometimes not) who are familiar with scripting look at it and see if my comments in the code allow them to follow what it is doing and why. Their questions or confusion indicate places where further exposition is required.

        1. The Oncoming Scorn Silver badge
          Pint

          Re: Literally

          I write scripts to automate as much of my job & ensure consistent results every time.

        2. Doctor Syntax Silver badge

          Re: Literally

          find out who the manager or lead thinks are the least clueful people on the team that will be using it, and have them run it

  5. Adrian 4 Silver badge
    Holmes

    Measure twice, cut once

    Not going to condemn him, and quite rightly, it appears his employers didn't either.

    But wasn't that 6 months of petty jobs supposed to determine that he wasn't stupid, and that some things, like the Big Red Button, are not used lightly ? On your very first responsible operation ?

    I would have expected him to at least ask, unless they'd drilled every last bit of initiative out of him. In which case they deserved it.

    1. elsergiovolador Silver badge

      Re: Measure twice, cut once

      I would have expected him to at least ask

      That also may be a cultural thing - whether in the company itself or how the person in question has been raised or just how they are wired (extremely introverted).

      If someone has already developed the impostor syndrome, then prospect of validating it by advertising to the world they don't know something perceived as basic by other employees, may be particularly terrifying. Especially if you are month away from being homeless if you don't get paid.

      That being said, I particularly liked the culture where it is said time and time again there are no stupid questions and there is no judgment as everyone makes mistakes and everyone has bad days when their brain is not up to the task. So people are comfortable asking and question even the most basic stuff.

      1. Peter2 Silver badge

        Re: Measure twice, cut once

        If someone has already developed the impostor syndrome

        If? Everybody gets it on occasion. I'd like to reference this:-

        https://journal.neilgaiman.com/2017/05/the-neil-story-with-additional-footnote.html

        Some years ago, I was lucky enough invited to a gathering of great and good people: artists and scientists, writers and discoverers of things. And I felt that at any moment they would realise that I didn’t qualify to be there, among these people who had really done things.

        On my second or third night there, I was standing at the back of the hall, while a musical entertainment happened, and I started talking to a very nice, polite, elderly gentleman about several things, including our shared first name. And then he pointed to the hall of people, and said words to the effect of, “I just look at all these people, and I think, what the heck am I doing here? They’ve made amazing things. I just went where I was sent.”

        And I said, “Yes. But you were the first man on the moon. I think that counts for something.”

        And I felt a bit better. Because if Neil Armstrong felt like an imposter, maybe everyone did. Maybe there weren’t any grown-ups, only people who had worked hard and also got lucky and were slightly out of their depth, all of us doing the best job we could, which is all we can really hope for.

        (There’s a wonderful photograph of the Three Neils even if one of us was a Neal at http://journal.neilgaiman.com/2012/08/neil-armstrong.html)

        Nobody is an expert on everything. If anybody tries to make out they do know everything and have nothing to learn are then they aren't all knowing and impressive, they either do not understand the depths of their own ignorance and stupidity (See "Illusive superiority", or the "Dunning Kruger effect") or they do know how limited their knowledge base is, and deter questions lest somebody betray the fact that the emperor has no clothes.

        Admitting the obvious point that nobody is all knowing in every area and that different specialists have different knowledgebases means that people can shrug their shoulders occasionally and say "not really my area; so and so knows more than me in that particular niche". If everybody can be big enough to do that life is so much more pleasant for everybody.

        1. SCP

          Re: Measure twice, cut once

          If anybody tries to make out they do know everything and have nothing to learn are then they aren't all knowing and impressive, ...

          As the pithy observation goes - "I'm not young enough to know everything."

      2. Ken G Bronze badge
        Trollface

        Re: Measure twice, cut once

        As my engineering lecturer used to say "There are no stupid questions. Only stupid people."

        1. A.P. Veening Silver badge

          Re: Measure twice, cut once

          "There are no stupid questions. Only stupid people."

          There are no stupid questions ... but there are inquisitive idiots.

      3. PRR

        Re: Measure twice, cut once

        >> I would have expected him to at least ask

        > That also may be a cultural thing - whether in the company itself or...

        We watch a 'airplane disaster' TV show. Not-asking happens.

        But sometimes it is taken to extremes. Cockpit staff have been trained to NOT question the Captain, by national culture, by military culture, by social class expectations, and because the pilot is a bully. Like not telling the pilot about low fuel, or headed into a mountain, because he is on a rant about something else, or is really pissed at his girlfriend.

        After a run of these in the late 20th century, "some" training programs now emphasize that junior staff should be proactive and senior staff have to accept it.

        1. Christoph

          Re: Measure twice, cut once

          "After a run of these in the late 20th century, "some" training programs now emphasize that junior staff should be proactive and senior staff have to accept it."

          On a fully laden, just refuelled jumbo jet at Tenerife, the junior staff didn't want to question the captain's misunderstanding of a radio message as clearance for immediate takeoff.

          Some of the people in the jumbo that was taxiing up the runway in thick fog survived.

          Aircraft now wait for departure. The word takeoff is used only for authorising or cancelling immediate takeoff.

    2. Doctor Syntax Silver badge

      Re: Measure twice, cut once

      "I would have expected him to at least ask"

      Ask what?

      The instructions were clear. They were incomplete but with no indication of that.

    3. David Nash Silver badge

      Re: Measure twice, cut once

      to be fair, it did sound like they had it drilled into them to just do exactly what the instructions say.

  6. Andy The Hat Silver badge

    I can't be the only one ...

    The "title graphic" is a Haynes manual page. Definitely a gearbox with rear output shaft ... but from what?

    1. Loyal Commenter Silver badge

      Re: I can't be the only one ...

      Well, I can tell you it's pp 54-55, Chapter 3, "Fuel and Exhaust Systems", but I guess the actual manual title is in the page footer.

      I'm going to take a wild guess and say, Ford Cortina. Life's too short to go searching for PDFs of various Haynes manuals to work out exactly which one.

    2. Graham Dawson Silver badge

      Re: I can't be the only one ...

      Triumph Stag, from the look of the rear.

      http://classiccars.brightwells.com/viewdetails.php?id=10455

      http://classiccars.brightwells.com/images/lots/ats6.jpg

      1. Atomic Duetto

        Re: I can't be the only one ...

        beat me to it.. had a mate with one of those, generally we all came back in my car (Kingswood)

  7. Anonymous Coward
    Anonymous Coward

    Write Idiot Guides if you want to hire idiots

    Before retiring, one of my roles was to help organisations document their systems (not expressly ICT, but almost every one involved it). The industry I was in had started out with a distaste for written instructions but, as regulations came in (it was a very high safety/environmental risk sector), a taste for very detailed documentation came in. The trouble was that most of the major players paid well and was able to hire a skilled workforce - whose members rarely took kindly to being told how to do their job. Some organisations enforced compliance with their written tomes and some, one in particular, did well (their strength was keeping change to a minimum and maintaining their successful projects for longer than the norm). Others were more relaxed and also did well (again, one became a market leader whose strength was in tackling new ventures, not afraid of failure, and not clinging onto their old successes - selling them on when they needed the more rigid approach).

    My own approach is to treat the need for detailed procedures for routine/repeated work as a management (including HR) failure. Develop checklists for individual tasks and process maps to describe how they fit together. Manuals and technical guides should be available for reference but, if you hire the right staff, train them (and encourage CPD), and empower them to use their skills, you will get the best. There will be mistakes, but you treat those as opportunities to learn and improve. (When I say "mistakes" I don't mean disasters - those happen when you don't learn).

    Just my 2¢ to lob into the discussion...

    1. Korev Silver badge

      Re: Write Idiot Guides if you want to hire idiots

      Wasn't there huge resistance from surgeons to introduce checklists? The doctors regarded it as an affront because "who on earth would forget to take a swab out of a patient?", but since they were introduced medical errors have fallen

      1. Benegesserict Cumbersomberbatch

        Re: Write Idiot Guides if you want to hire idiots

        The perianaesthetic Time Out: bane of the operating theatre, but it has abolished operations being done on the wrong patient (or the wrong operation being done on patients, if that's your preference)!

    2. Doctor Syntax Silver badge

      Re: Write Idiot Guides if you want to hire idiots

      Bear in mind that at some stage a manager might try to carry out the operation.

    3. DS999 Silver badge

      Re: Write Idiot Guides if you want to hire idiots

      Regulations say you have to write the instructions, but whether people follow them is up to them and the company. If the penalties for mistakes resulting from not following the instructions are not that high, the company may not care if the highly educated employees do it how they like, so long as they accept the potential risk of being fired if they make a mistake following the instructions to the letter would have avoided and a scapegoat is necessary.

      Probably everyone reading this has deliberately not followed the instructions in some cases. Maybe they specify to use the GUI, and you know the CLI and can get things done much faster that way (either because the GUI is slow as molasses or because you can complete multiple tasks in parallel using various CLI tricks) Or maybe the instructions are written for the lowest common denominator, and you know what shortcuts are applicable in a certain situation. Or in many cases, you know or assume the instructions are not very good and you'd end up like the protagonist in today's Who Me if you slavishly followed them.

      Even if it results in a mistake once in a blue moon, most managers will think the greater productivity of smart people working how they want is worth it. Obviously that's not a thing in life critical stuff, or where a single mistake could cost millions of dollars, but most work is neither - even in places were some work is.

      1. A.P. Veening Silver badge

        Re: Write Idiot Guides if you want to hire idiots

        If I know the instructions are not very good (or even completely wrong), I usually rewrite the instructions and ask some colleagues to review the changes.

  8. Anonymous Coward
    Anonymous Coward

    Doncha hate it...

    ... when the instructions are just '1. do X, 2. do Y, 3. do Z', with no explanations. You often find that once you understand the process you can often improve an old process to make it better/safer/quicker. (I'm thinking of a bunch of old local documentation where, as a newbie, after a few mins research 3 or 4 individual commands were replaced with a single safer all-in-one command)

    Unfortunately even the better suppliers can supply duff info. I once tried to upgrade a Cisco Nexus switch only to discover the documentation was not just lacking, but down right wrong. I ran the command that checked the compatibility of the new image and got the same results they gave as an example. I then went to run the install command... but it wasn't there! I tried using the install command 'borrowed' from the 'downgrade' section but it just ran the compatibility check then stopped, leaving the existing image. After a lot of further faffing and with different combinations it dawned on me that the compatibility check had been saying 'incompatible image' all along, just as the documentation showed, and possibly that was a problem (don't know what Cisco's reason was, but mine was that the image came as 2 files that should have been the same version but one was .7a and the other .7b)

    1. J.G.Harston Silver badge

      Re: Doncha hate it...

      I aim to get instructions down to a single page of A4 so it doubles as a checklist you can tick off as you go (or fill in details, eg user's name, user's logon name, user's email address, etc), and anything that's too long to fit as an aide memoir is referenced to supplementary sheets. Once you've gone through it a few times ticking off while refering to the supplementary sheets, you only need them for occasional reminders.

      So, eg:

      Update A/D user details with (see D):

      name, building, address, email address, change password:Yes

      With D saying something like:

      Start->Admin Tools->Active Directory Users and Devices->RunAs->your admin ID

      View -> Turn Advanced Settings on

      blah.thing.uk->North->Yorkshire->(site)->(user)->Menu:Properties

      General: name, job title, site

      Address: site address

      Account: etc etc etc (I'm working from memory)

      Most of the time once you're familiar the two lines in the checklist is enough, but every now and then you have a brain fart and think: where's the proxy address? WTH is it???? Check notes, ah! Dammit, need to bloody turn bloddy advanced bloddy view on.

    2. J.G.Harston Silver badge

      Re: Doncha hate it...

      The thing I really hate is when the documentation outright LIES. I don't call it "wrong", it's plain and simpel LYING.

      Eg: (blah blah....) drop down, select 'Import All'

      THERE IS NO "IMPORT ALL" OPTION!!!!11111!1!!!11!1

      Several frustrated days of back and forth with the "further up" helpdesk... Oh, you have to have permission XYZ to do that.

      WTF!?!!!??!?!?!?! First rule of interfaces: If an option is unavailable, MAKE IT VISIBLE SO YOU F*********ING WELL KNOW IT'S THERE BUT UNAVAILABEL!!!!!!!!

      1. DS999 Silver badge

        Re: Doncha hate it...

        That sounds like a case where someone with higher privileges was writing instructions intended for someone with lower privileges. That's why they need the step of testing with an ordinary user of their end product, rather than a colleague who has the same higher privileges.

      2. Anonymous Coward
        Anonymous Coward

        Re: Doncha hate it...

        I recently moved and tried to get my address changed with USA Social Security Administration. Found instructions online, signed in - the menu option to do it simply didn't exist. Found several other sets of instructions to do the same thing - referring to the same nonexistent menu option. Finally called them, waited half an hour to get a real human being, who walked me through the steps - to use the same nonexistent menu option.

        Turns out that if you're not receiving benefits at the time, there's no way to update your address (it hides the menu option). They use the one from your tax return instead. Grr!

    3. SCP

      Re: Doncha hate it...

      You often find that once you understand the process you can often improve an old process to make it better/safer/quicker

      I agree with your dislike of instructions without explanation - but explanations can also prevent critical steps being optimized away because somone does not understand their purpose.

      Picking up on your "better/safer/quicker" point: too often I found cases where steps had been introduced into a process to address a problem that was occuring elsewhere (but could not be immediately corrected). Unfortunately the additional steps remained long after the problem had been rectified because the reason for the step being there was not made clear (and it was not immediately obvious that the step was redundant).

    4. John Brown (no body) Silver badge

      Re: Doncha hate it...

      "... when the instructions are just '1. do X, 2. do Y, 3. do Z', with no explanations. You often find that once you understand the process you can often improve an old process to make it better/safer/quicker. (I'm thinking of a bunch of old local documentation where, as a newbie, after a few mins research 3 or 4 individual commands were replaced with a single safer all-in-one command)"

      One particular brand of kit we maintain, you are not allowed to work on until you complete the manufacturers service training. Then you take a test to prove you have taken it in and understand it. Then you get set loose on the kit to fix it and the instructions are written for dummies that almost anyone who knows which end of a screwdriver is the business end could follow. The procedure involves an almost compete strip down of the kit to replace the part over about 90 mins, including re-assembly and testing. Anyone who has completed the course, by definition, understands the kit and the prcess and can replace the part without a full strip down in about 10 mins with 5 mins for testing. Who's right? Depends on if it works afterward :-)

  9. chivo243 Silver badge
    Facepalm

    I love documentation

    that gives you the procedure in steps, and down about 5 steps later it says, But, First, perform X... before doing S. D'oh! There was an episode of MASH when Hawkeye had to dismantle an unexploded bomb in the compound, Henry reads the instructions, remove the tail assembly, cut the wires leading to detonator, Hawkeye and Trapper cut the wires, Henry then reads further, but first remove the fuse! Priceless!

    1. Ordinary Donkey

      Re: I love documentation

      I worked one place with instructions for everything, but one section only explained how not to perform that task with no information on what you were actually meant to do.

    2. DS999 Silver badge
      Trollface

      Re: I love documentation

      It seems this has been a problem for centuries - "the warnings come after the spell!"

  10. Loyal Commenter Silver badge

    Decent instructions...

    ...should contain the reason for each step, and the expected outcome. They should impart at least enough knowledge to the person following them that they should understand what they are doing, rather than just following it slavishly. This should at least help guard against things going completely off the rails, although you can never guard against wilful stupidity.

    Oh, and instructions that don't start with "read these instructions IN FULL before commencing" or similar are not fit for purpose. If the person following them chooses to ignore that primary instruction, then on their head be it. I have seen plenty of instances of "ignore the previous step" kind of revisions in documentation that make this vitally important.

    1. Loyal Commenter Silver badge

      Re: Decent instructions...

      ...and to clarify, the reason for that "read these in full" instruction is because you can't control the actions of others in the future when they come along and butcher your document. At least, by requiring the reader to read to the end, you're giving them the chance to see and read out-of-order instructions that others might cause, before they work through the instructions and miss out such steps.

      Documentation is rarely set in stone, so you should treat anything you produce as transient.

      1. A.P. Veening Silver badge

        Re: Decent instructions...

        Documentation is rarely set in stone, so you should treat anything you produce as transient.

        And even if it were set in stone, stone can be broken.

  11. steveg123
    Coat

    Idiot proof

    I find that the best way is to ask my immediate supervisor to "test that my documentation is idiot-proof". Most of the time they don't realise that they are being insulted.

  12. Sam Therapy
    Happy

    Ah, Malicious Compliance. Where would we be without it?

    1. Anonymous Coward
      Anonymous Coward

      A previous co-worker pointed out that the easiest way to get rid of a disliked rule was draconian enforcement. For instance, our safety rules stated "Hard hats must be worn 100% of the time." Most of us worked in an office. If we had wanted to get rid of the rule, then give a written warning to every single office worker for not wearing a hard hat at their desk, notify Corporate that adherence to the hard hat policy is <5% and we need them to come give us all a talking-to - and then when they step out of their car, report them for being onsite without a hard hat. Rule would be changed IMMEDIATELY.

      1. Fred Daggy Bronze badge
        Mushroom

        Apocryphal story that did the rounds a while back about the Victorian (Austalian state) Police pulling up a car on the freeway belonging to the Worksafe Authority, for speeding. Cop wanders over and give the drive a find for $Au100 worth of beer vouchers. Ouch. Reason: Exceeding the speed limit.

        "Fair cop gov" and no hard feelings.

        Work Saftey Officer dons high-vis vest, leaves car and hands Plod $Au350 find for operating in a dangerous area (side of freeway) without appropriate protective clothing. To wit: One high-vis vest.

        Justice served.

  13. Tubz

    In my job if I right manuals or just basic guides, I have to dumb it down to braindead management level, too ensure it is understood down the finest detail and followed to the letter. if it then goes wrong, I look for the signature that signed it off and pass the blame, we all play the protect your own backside in the blame game !

    1. J.G.Harston Silver badge

      Have you deliberately written it like that to make everybody's inner proof-reader scream in pain? ;)

      1. Doctor Syntax Silver badge

        The pain eases somewhat if you print it out so that you can mark it up.

  14. heyrick Silver badge

    I'm leaning towards "not his fault"

    They make it clear that the instructions must be followed (translation: do as you are told, not what you think).

    They provide instructions to follow that omit to mention a fundamentally important step (not up to me to realise if I'm following what it says to do).

    They need to realise that it is vitally important for the little guy to follow the instructions provided until such time as that person has sufficient seniority to write new instructions (this is basic ass covering, if one does what they want and it goes wrong the world lands on their head, but if you're just following instructions to the letter as you were told then the fault is with the instructions).

    He probably should have realised, but it sounds like the company made it clear that thinking wasn't what he was being paid to do.

    1. Doctor Syntax Silver badge

      Re: I'm leaning towards "not his fault"

      I agree up to "He probably should have realised". Why? What clues were there that there was something to realise? Without the information that reboot should only be carried out on a shut down machine it seems like a straightforward instruction.

  15. Filippo Silver badge

    I used to try to make my docs as foolproof as possible, until I realized that nobody reads them. Like, ever. As in, sometimes I sent out the wrong PDF by mistake, and nobody noticed. "Last access" date is invariably the date I performed system installation. The operators don't read them, the supervisors don't read them, the bosses certainly don't read them.

    If anyone needs to know how to do anything, they call me. If I point out that the answer was in the docs, they'll express surprise at the existance of the docs and say that they'll read them. But they won't. This happens every single time.

    Sometimes they have a quality certification guy or something like that, who'll ask for the docs. He attaches them to his report, but doesn't read them either.

    Fortunately, these are all industries where failure is not very dangerous.

    1. yetanotheraoc Silver badge

      This happens every single time.

      Where I work, the only people who read the instructions are the auditors. And the only time the instructions match what the users _should_ actually be doing is when the auditors are arriving imminently.

    2. Doctor Syntax Silver badge

      They will be read when it's important, i.e. something has gone wrong.

      You can read them out to whoever is asking why it went wrong. You are covered and can direct the blame elsewhere. When all else fails that's what documentation's for.

  16. John D'oh!

    Never assume anything

    At my previous company I was once called down to the test department because the poor guy had followed the documented procedure to the letter, but nothing was happening.

    When I got there I could see that he had indeed typed the command in exactly as described in the documentation, so I pressed 'enter' and everything worked as expected.

    I then went back to my office and added "and then press 'enter'." to the procedure in question.

    1. John Brown (no body) Silver badge
      Coat

      Re: Never assume anything

      "I then went back to my office and added "and then press 'enter'." to the procedure in question."

      There's no key on my keyboard labelled "Enter". What do I do now?

      Before answering, bear in mind that the key may be marked "Return". I may have as well as or instead of the relevant word, just a left arrow with a vertical bar and they key may not the be shape you think it is.

  17. Dan 4th

    E = mc2

    E is Experience

    m is tiMe

    c is mistaKes.

    1. Anonymous Coward
      Anonymous Coward

      Re: E = mc2

      One of my favorite cases from The Codeless Code: Ten Thousand Mistakes

      http://thecodelesscode.com/case/100

  18. Richard Pennington 1
    Black Helicopters

    Many years ago (before I retired) ...

    ... I was called on to write a set of Security Operating Procedures for the <ahem> system at <redacted>. These procedures went through - line by line, in mind-numbing detail - every operation available to a user or to an administrator (at any level) in the system. In terms of structure, there was a main document, and annexes A, B, C, ... up to about M, and finally Z.

    Annex Z was so titled, so that it would always be the last annex, and could be pulled off the rest of the document and issued separately. It contained a summary of the rest of the document, filleted so as to include only those instructions relevant to users without specific security or system-administrator responsibilities.

    1. Doctor Syntax Silver badge

      Re: Many years ago (before I retired) ...

      Did nobody demand to know where annexes N to Y were?

      1. Anonymous Coward
        Anonymous Coward

        Re: Many years ago (before I retired) ...

        "This Page Is Intentionally Left Blank"... "This Page Is Intentionally Left Blank"... "This Page Is Intentionally Left Blank"...

  19. Anonymous Coward
    Anonymous Coward

    first: "Reset CPU."

    After reading this, unless he was hard locked in dummy mode, he should really have asked himself: what happens to that things using this CPU, like OS, and anything managed by the OS ?

    But he got his answer quite quick, me thinks :)

    1. doublelayer Silver badge

      Re: first: "Reset CPU."

      I disagree for two reasons. The first reason is the wording. If the instructions say "first", they mean there is no step before it. He shouldn't go looking for one, and had he performed a shutdown when the instructions didn't call for one (and didn't need one), there's no doubt he'd have been blamed by everyone, including the posters here.

      The second reason is that, especially when the procedures are thoroughly documented, it's reasonable to think that the process might have been automated. I'm not sure what "reset the CPU" entailed in this situation, but if it was a command, it wouldn't be unreasonable to assume that running that command would perform operations like shutting down. The format of the instructions would imply that was likely. If I'm told to run this command to perform a reset, I'm more likely to trust the people who have done this several times and could have made the command perform an orderly shutdown of all services rather than assume that I should perform my own basic shutdown instead, because there's always a chance that the scripted shutdown does more than just telling the OS to halt.

      If the policy is that I always follow the procedures to the letter and it's plausible that the procedure I'm reading is exactly what needs to be done, I don't think there is any blame due to him.

  20. Kev99 Silver badge

    Never apologise for those thongs over which you have no control. Especially instructions written by someone who never actually did the work.

    1. Loyal Commenter Silver badge

      Freudian typo?

      1. Ian 31

        Look at your keyboard, I is next to O. Fat fingers, nothing Freudian.

        1. Loyal Commenter Silver badge

          I have no need to do so, because (a) you appear to have missed the very obvious joke as it flew over your head, and (b), I have been using a QWERTY-layout keyboard, on a daily basis, for well over a quarter of a century, and could confirm that without examining the order of the keys.

          Anyway, apart from everything Freud said being essentially bollocks, who's to say it's not the OP's subconscious causing his finger to momentarily shift to the left just to prank them?

          1. Filippo Silver badge

            Besides, it's still good advice. I'm certainly not going to apologize for any underwear over which I have no control.

            1. Aussie Doc
              Joke

              Re:

              I came to say something similar but for footwear rather than underwear.

              Here in Oz thongs usually comes in pairs and are worn on feet (or thrown at head by angry mum).

              AKA flip-flops in some places, I believe.

              Still, these days auto-correct will have anybody typing something they didn't Nintendo.

          2. A.P. Veening Silver badge

            Anyway, apart from everything Freud said being essentially bollocks, who's to say it's not the OP's subconscious causing his finger to momentarily shift to the left just to prank them?

            According to my ((QWERTY) keyboard, the "O" is to the right of the "I ".

            Severe case of Muphry?

            1. Loyal Commenter Silver badge

              How do you know which way up they were holding their keyboard?

              (phew, think I got away with that...)

        2. Doctor Syntax Silver badge

          "Look at your keyboard, I is next to O"

          Keyboard layout being assumed here.

          1. Loyal Commenter Silver badge

            To be fair, those keys are next to each other in both the commonly used keyboard layouts for the Roman alphabet (QWERTY and AZERTY), on which the OP was likely to be typing. If they're using some sort of IME on a non-Roman keyboard (e.g. a Japanese, Russian, Greek, Korean, Simplified Chinese etc. layout) then it's more likely it was deliberate and not a typo (or the work of the evil autocorrect). Somehow I doubt that this was the case though.

  21. Doctor Syntax Silver badge

    What really annoyed me was having to write instructions for the DBAs to set up new products with SQL commands when I'd already written a maintenance screen that did all the necessary work of glueing together the surrogate keys, etc.

  22. VTAMguy

    IBM and Amdahl mainframes

    Not AMDAHL as it was a name, not an acronym. Gene Amdahl. They had a pretty interesting Unix called MTS. And some mainframes too.

  23. Boris the Cockroach Silver badge
    Facepalm

    RTFM

    But what if your manual has been translated from Japanese into English by contract translators who just do a word for word translation and never bother reading it to see if it makes any sense.

    At least the german robots are a bit closer to english so when the manual makes no sense we can go back to the original german..(and that sometimes makes no sense either!)

    1. A.P. Veening Silver badge

      Re: RTFM

      At least the german robots are a bit closer to english so when the manual makes no sense we can go back to the original german..(and that sometimes makes no sense either!)

      That is because the original German isn't original at all but translated automatically from Chinese.

  24. Anonymous Coward
    Anonymous Coward

    No one has mentioned instruction by GUI......

    Strange, isn't it?

    In many cases the manual is only two lines long (say for a WiFi router):

    (1) Plug in the device and switch it on.

    (2) Follow the instructions on the startup screen.

    .....but don't get me started about "cloud" installs!!

    BAD GUI EXAMPLE

    In a somewhat different world, my all time favourite happens when you have a Fedora Live Image running.

    Then you click the "Install to hard drive" icon, and a bare metal install starts.

    After some simple, easy to understand screens, the happy user gets to setting up disk partitioning.

    I still haven't a clue about how to preserve an existing /home partition using the install GUI....even after doing hundreds of bare metal installs!!

    INSTRUCTIONS ON HOW TO PRESERVE THE /home PARTITION

    (1) Do an install with a new (empty) /home partition. (The GUI is simpler for this task)

    (2) Restore /home as required

    (3) Do all subsequent Fedora upgrades (e.g. F35 to F36) using a terminal session and the dnf command with "system-upgrade" and "releasever=36" parameters.

    Steps #1 and #2 only need to be done once. Step #3 is done for every Fedora upgrade...and no GUI needed!

    Voila.....never need to do a Fedora bare metal install again!......hopefully!!

  25. Scott 26

    Writing docs in our team we used to hand it our to one of our juniors to test in a lab. You heard of "foolproof" - we had to make our doco "xxxxxxproof" (name redacted to protect the guilty).

    He would find anomalies and missed logic like one of those K-9 sniffer units at the airport.....

  26. rob123456

    Not me, but someone who was likewise a freshly minted graduate at the time. Familiar with DOS and Unix but new to MVS+TSO. First week on the job, typed 'cls' to clear screen. Unfortunately, one of the more senior devs had created a macro or some such for 'cls' that mapped to a command 'close' that shutdown the system.

  27. Rtbcomp

    A Picture Paints a 1000 Words

    I like those technical manuals that have a picture of the kit on the front cover, at least you knew you were using the correct manual to fix the darn thing.

  28. NITS

    Rule 1: Start every step with a verb.

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

Biting the hand that feeds IT © 1998–2022