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

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.

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

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 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 and enter the following... only for the user to say "Where's ?"

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.

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 also remember how much people struggled to coordinate the Shift - Break key combination to load a programme from a floppy disc on the BBCs

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.

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.

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.

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

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