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
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 …
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.
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.
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.
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.
"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 !!!
:)
"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?
"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.
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".)....
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.
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.
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.
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.
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.
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.
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
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.
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>?"
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).
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".
"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.
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
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.
"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.
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.
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.
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.
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!
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.
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.
"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.
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/
. . .
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.
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.
This post has been deleted by its author
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).
"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.
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.
"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.
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.
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.
I remember that. The exam that really stood out was the one where the you had had us use a specific word in the answer to one of the questions to get the extra mark...I think it was eskimo. The other question was "If CSCI??? was made into a movie, what would the title be". My answer was "Victims of the Preying Manis".
> *) 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?
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...
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.
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.
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.
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!
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.
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).
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,
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!"
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.
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
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.
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.
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.
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.
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.
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.
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.
>> 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.
"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.
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.
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...
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.
... 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)
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.
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!!!!!!!!
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.
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!
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).
"... 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 :-)
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!
...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.
...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.
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.
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.
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 !
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.
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.
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.
"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.
... 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.
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.
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?
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.
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.
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!)
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!!
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.