Just follow the instructions … no wait, not that instruction to lock everyone out of everything Welcome, gentle reader, to another instalment of Who, Me? in which Regizens recount records of rancor and remorse. This week, a tale of instructions designed to make life easy that did, in fact, nothing of the sort. Our story starts with "Harry" who, back in that far-off time we call "the day," was an install engineer – a …
The manual was written by a tech writer and sales reps
The manual could have been originally written in Chinese, and poorly translated to English (Chingrish is what I've heard the resulting product referred to as)
My girlfriend and I just installed a fandelier (the fancy term for ceiling fans with lights these days, apparently...I hadn't heard it before but she looked at me funny when I said that lol) in the bedroom of her new house last night.
Not only did the manual barely touch on how to put everything together beyond a couple crude drawings, the instructions were comically bad. It referred to the electrical neutral as "zero line" and hot as "performing line", but fortunately the wire insulation colors made it obvious what was what. The remote control was called "distant switch", or at least that's what we guessed.
Fortunately we had just installed a different fandelier in her living room last week, and even though they were different brands (the other had detailed instructions that were either originally written in English or translated by a fluent speaker of both languages) and it was similar enough we figured it out after we stopped laughing at the tiny sheet they'd provided.
I have to agree. +1. Perhaps all the good stories have been told? They are relying on reader contributions for the stories*. However, this is really just part of the vanillaization (the opposite of vandalization?) of El Reg, now known as Reg.com.
*I know I don't see some user handles in the comments any longer. Have they gone AC? Doubtful, they probably aren't visiting Reg.com and this brain drain is affecting the quality of columns like Who? Me? and On Call.
What's the objection there from the down-voter? The Shakespeare quote, or the chastising of Dave Gibberish's constant poor-quality trolling?
edit - I'm the same poster BTW, I thought it might be time for a name refresh, partly as an experiment to see if those systemic single downvotes are powered by GREP...
The most obvious rebuttal is to note that you're the only person I've seen ranting about this alleged move to the "alt right"(!), and yet- aside from some of your more inflammatory/unhinged comments getting removed- you're still free to post shite like this!
Said it before and I'll say it again- if you think that the Register is "alt-right"(!) even today, you're either a troll or the left-wing counterpart of the US Conservatives who think their Democratic party is "Marxist". (Or the former masquerading as the latter).
The only major jump "El Reg" has made in recent years is their clear attempt to make it far less obviously a UK-based publication and aim it more at the US audience.
"The only major jump "El Reg" has made in recent years is their clear attempt to make it far less obviously a UK-based publication and aim it more at the US audience."
Speaking as a member of that audience, note that this move to become "less UK" has made el reg considerably less appealing. It's not like there's a shortage of "US" over here. :P
There's been a lot of bans handed out to those who criticise the jump towards the alt-right that has been made.
What has utterly confused me is that you have labelled things the left and liberals have done, or would be ideologically inclined to do, as alt-right ideology.
While willing to accept the very-far-left and very-far-right are as bad as each other at the extremes of the political spectrum, the things you complain about are simple left-wing leanings which you label alt-right. The shift you perceive towards the alt-right is actually what I would call a shift to the left.
Criticise the left all you want but labelling them alt-right is ridiculous.
Likewise. I have started to link to the last time I commented on a similar story rather than typing it out again. Just as there are seven basic plots, there are a limited number of ways in which we can press a button, lose a backup or insert a thing the wrong way up. Or maybe I'm just too old and have seen too many things.
"* El Reg's readership is very old
* The younger generation is smarter, more skilful, and less prone to making mistakes."
Then again, perhaps the younger generation is simply less willing to admit to those mistakes, as the passage of time makes such admissions feel somewhat less threatening.
Third possible explanation, the younger generation is "standing on the shoulders of giants" and is working in an environment where things like locking everyone out has become much much harder to do accidentally because the grey-beards have long ago learned from the mistake and set up processes to prevent it happening again.
You often see comments like "why was it even being done that way?Best practice is to..." by people who were taught best-practice in years that start with a 2.
Truth is that the industry has learned a lot, the hard way, and often old El Reg stories are about those hard lessons being learned.
Indeed. I gather (through hearsay, not experience) that pilots have a long, *long* preflight checklist -- and it's been said that every item on that list has its origin in a lesson learned the hard way.
Well, pilots have collectively been at it for roughly half a century longer than we have, so more of our hard-way lessons were presumably learned within living memory although, also presumably, skewing towards the older part of that range.
(I'm sure the aviation world still has its lessons yet to be learned, just as I'm sure we do too.)
That comparison has a problem: Most procedures don't risk life of many people. If something goes wrong in aviation quite often over 100 people end up dead. And every bigger accident is world wide news. Flying is, practically, always flying. So the check-lists are mostly universal, except for plane specifics which are only similar. Most of IT does not cost lives. And where it can cost lives outside pressure forces IT documentation on a different level, like aviation, clinics, automated driving and so on.
... Kind of like how the OHSA* rules are (more or less) 'written in blood'?
while I will sometimes make fun of health & safety when it's taken overboard, there is (usually) a good and sensible reason for why the laws are there, and it because someone was killed or maimed.
*Occupational Health and Safety Administration, which is a US federal level department within the government here; not sure what the UK equivalent would be..
When computer systems were mostly about counting beans or tracking things on shelves mostly nobody died ( with a few exceptions like those unfortunate enough to sub contract for the UKs post office ).
However now we have millions of lines of code running in cars, industrial machinery, tractors, speakers and light bulbs FFSK. The opportunity for accidental or deliberate mayhem is pretty much unlimited.
PS I do agree with other posters about the sad decline of the once great vulture, now more of a dying parrot. The old tounge in cheek tabloid style is now more like a local free sheet, and, when I read about a major Google outage in the Guardian without any mention in El Regette it is clear that it’s not just a loss of humour.
Well, pilots have collectively been at it for roughly half a century longer than we have, so more of our hard-way lessons were presumably learned within living memory although, also presumably, skewing towards the older part of that range.
(I'm sure the aviation world still has its lessons yet to be learned, just as I'm sure we do too.)
Towards the end of his life, my father passed on advice that he was given in the WW2 RAF: "Do not leave an aeroplane by parachute unless the aeroplane is on fire". This would still seem reasonable to many of us. As a passenger, I have expanded this to only use large commercial aircraft, preferably in the nicer bit at the front, and I forgo the parachute completely...
I think that, on balance, I would go with the millions of lines of code - Current commercial passenger fatalities are ~1 for every 2.5 billion miles travelled. It seems unlikely that the descendants of the WW2 German and Italian armed forces would be actively trying to kill me.
The WW2 RAF fatality rate from flying accidents, etc., was ~8,000 out of >55,000. This compares to a total aircrew fatality rate of >44%. For volunteers, the casualty rate (deaths, POWs, seriously injured) was >60%. These figures are mostly for bomber crews, the total number of Battle of Britain fighter command casualties was ~550 out of 3,000.
I was thinking the same. The wild west of IT has passed and we are now in a stable state where most things are done using established tools so the possibility of a bad command is greatly reduced. Clicking SnazzyExpensiveBackupSolution on the deskop is going to have fewer routes to disaster than a mistyped dd command.
I still do my backups with dd though so maybe there will be a post from me in the future but as I am careful then nothing can go wrong!
And yet another explanation is that the younger ones are still employed at a level where they won't admit to making mistakes that could get them fired if identified. It's a lot safer to recount a tale of disaster that happened decades ago in a different life under a different, possibly now defunct employer :-)
"The younger generation is smarter, more skilful, and less prone to making mistakes"
No they're not. They are no smarter than anyone else (In fact quite the reverse sometimes), highly skilled at one or two particular things rather than a cohesive skills portfolio*, and make just as many mistakes as the rest of us.
In addition, I think the latest generation is generally incapable of admitting a mistake - it is always someone or something else's fault. I have dropped several bollocks in my career, and each time I 'fessed up immediately. Most were my fault, the others turned out not to be. Mistakes are human and to be expected, so not admitting to them already marks you as less than honest, or a total narcissist who doesn't give a toss about anyone else. God help you if I find you trying to cover it up or pass the buck.
Most of my managers have been professional enough to say 'You what!' first, closely followed by 'Thanks for the heads-up...now how do we fix it?'. As for the other type of manager, well, you find them everywhere.
Their biggest failing IMO? Not being able to ask for help or say 'I dunno how to do that'. They just seem to plough on digging themselves ever deeper and hoping that it'll work out in the end.
* Got one at the moment...knows everything about a couple of subjects, but little or nothing about the stuff above or below that they are required to interface with (Full stack developer, my arse!) They just can't seem to 'join the dots', even after going to uni/college. On paper, they are brilliant...in practise, less so.
In defence of the young ones, that is also frequently the result of bad management. Us greybeards have grown up in a system where IT was rare enough to be a bit careful with the people you employed as skilled people were (a) hard to come by and (b) not yet managed as mere numbers on a spreadsheet that get culled when things went bad or it was bonus time.
I had to sack quite a few of those dipsticks that somehow made it into a company who were bad managers and instead of cultivating the young talent were running power games, politics and other crap that had nothing to do with management. The good news is that older people people like me now have (a) the skills to spot these wastes of space and (b) the power to ruthlessly rip them out of the structure like the useless weeds they are.
It's those people that kill work culture, and every time I'm able to catch one of them and boot them out it's a happy day. HR departments don't like me because I tend to trace back how they made it into the company, and somehow you'll find the root of the problem (to stay with vegeratian compatible phrasing) often resides there.
Those who do not try to help the younger generations forget one important fact:
They'll eventually choose the care home you'll end up in :).
Lately, the Who, Me? stories seem to be very old. Some may find the following explanations disturbing.* El Reg's readership is very old
* The younger generation is smarter, more skilful, and less prone to making mistakes.
Or maybe people only want to share old screwups to not risk their current employment and/or being sued for confidentiality reasons by their current or recent employer...
Or, having not yet been in the industry as long, the younger generation might simply not yet have the accumulation of war stories to tell.
Or (pure conjecture here) they might not yet have the confidence to tell the embarrassing ones. That might come only with age and (near-)retiredness, and the long-gone-ness of many of the organizations in question.
Agreed. "Who, Me?" and "On Call" are essentially the same sort of stories. It's just a question of whether it's the teller or someone else, respectively, that fucked up.
I think it might be worthwhile to combine the two columns into a new one, "War Stories" -- which would be a general enough name to also include stories that don't really fit into either of the existing columns.
You'd state the fuse rating when you described fitting it in the plug, then go on to describe how you checked the terminals were secure and the cord grip was correctly fitted. Then you'd mention the appliance power draw in passing so we could all nod wisely in anticipation of the punch line. Finally you would express disappointment at the lack of flashes and bangs.
A more entertaining tale to tell would be the one about an engineer in our ''R&D Lab who was tasked with checking a prototype lighting dimmer product was working as expected.
Instructions: Disconnect power, daisy chain the triacs, connect mains live, connect to mains neutral through a light bulb, set faders to zero, turn on, move the faders up, check bulb comes on.
Set-up done, power turned on, faders move up. World's Largest Bang (TM), lights go out, silence descends across the building, I was off my chair and under the desk like a ferret in a war zone, wondering WTF and what damage had been done behind me.
Thankfully engineer intact, albeit 'surprised', and no damage done except to the triacs whose tops had blown off. Turns out the whole lot was accidentally wired as a live to neutral short waiting to happen, the light bulb not in circuit.
Power back on. Cups of tea all round. "Shit happens" the most severe recrimination. "Power through local circuit breaker" and other safety advice added to instructions. And we all lived happily ever after.
Absolutely!
A depressing number of stories resemble Sir Walter Raleigh’s tale of the time he fell overboard and was almost eaten by a hammerhead shark, and the magic phrase “flames shot out” has been completely absent for years.
This is not The Register’s fault, it is that of the authors or these, well, one hesitates to call them Tales of Woe, centering as they do on conflagration-free non-firings. The young IT professionals of today are simply not trying.
It has to be said that the world of modern electronics to which they are exposed does not lend itself to loud detonations, people jumping around with their skeletons flashing on and off, and breakers at the substations tripping. One simply cannot get the same Oomph from a wall-wart designed to deliver 3 anna bit volts at a current so small it barely fibrillates the heart as one could in the late 1960s, when the St John Backsides Comprehensive “computer club” would turn on the floor-mounted socket with a three ring binder because there would be “some arcing” As the old IBM 1301 they were rebuilding from scrap began to stagger into half-life.
How I yearn for the days when a casually misplaced finger while pulling a crystal from a shortwave set could result in a loud cry of “OOYAH!”, an impressive standing long jump - backwards I might add, a hand-shaped burn in the desk top and the smell of frying finger flesh redolent in the air.
Not for the young engineer the exciting experience of leaving a screwdriver stuck in the ceiling after the reassurances of a colleague that the chassis of the TV was indeed unplugged turn out to be less-than definitive, nor shall their ears ever receive those energizing words: “SHE’S GONNA BLOW!”
I bought a trivial low power 12V plug in from Maplins (RIP UK supplier of electronics kit) about a decade ago. I plugged it into my wall outlet and there was a big bang and the main 32A breaker tripped. I removed it and there was a notch missing from the copper so proving the well known truism that fuses blow after the damage has happened.
I took it back to Maplins for a replacement and insisted that they plug the new unit into the wall there before I accepted it. She did so with notable hesitation and a worried look but it was fine
I heard a bit of a bang when I plugged a Nokia analogue mobile phone charger into my small desktop UPS - The charger was welded into the UPS. Yes, the circuit breaker tripped, but I also took out the 50A fuse under the power box, and the distribution cabinet in the street; leaving 26 houses without power. The electrician, and the nice man from the power company who he called out, were both quite understanding, under the circumstances.
So many PC cases have ludicrous numbers of colourful lights in them that last time I rebuilt my home PC I couldn't even source a motherboard without weird lighting effects (thankfully disabled in BIOS).
Maybe we can convince the youngsters that, if even whitebeards have them, LEDs are totally passe (e acute that is meant to be) that they have to move onto The Next Big Thing - which is, of course, the USB-C powered Jacob's Ladder. That should be good for a few hijinks.
I think there are some stories which are buried deep enough to never see the light of day again. Or maybe simply old crisis long forgotten.
A recent Who? Me? caused me to recall a story of my own.... I was proudly one of the first three students to get access to the Internet at my College in 1989.
For the youth among us, that meant a 1200 baud modem, sharing a pool of three dial-in numbers, and a command prompt. And remember, "World Wide Web" is different from the "Internet".
I was not-so-proudly one of the first two students to get access revoked. Who knew that running a fake mail script and sending an anonymous email to an instructor would be a bad thing. Probably would have gotten away with it if there were more than three student users, but since that was the case it was an easy problem to research.
And this formed the Genesis of all the 'Acceptable Use Policies' we now have to deal with. You're welcome!
"And this formed the Genesis of all the 'Acceptable Use Policies' we now have to deal with."
Nah. We kicked a kid off the Stanford network for policy violations after he sent a "Wanna Buy My Bike?" message to every email address on campus in about 1982.
Every Datacenter in the Mainframe World had rules and regs about what was proper and what was not. The rules changed if you were on or off campus ... and if you were a part of the company who owned (or leased) the Mainframe, or were accessing it as a service bureau or (later) as a timeshare. Some of these rules were quite complex.
We had an AUP (of sorts) for the ARPANET in the early 1970s, although I could make a case for there being one as soon as the first bits were sent and received between two University campuses in 1969 ("Proper use of University Equipment" and "Sharing of Research between Universities" or similar went back decades before this).
Almost all BBSes had AUPs. Almost :-) [0]
Delphi had an AUP in 1983, BIX in 1984, AOL (as QLink) in 1985. The granddaddy of all of 'em all, CI$, by at least 1979, possibly as early as 1969.
[0] The AUP of mine read "Anything that unnecessarily increases jake's workload will get you terminated permanently. Other than that, have fun!" I never had to terminate anybody.
> 1989 .. the Genesis of all the 'Acceptable Use Policies'
1973, a bunch of us students had late-night access to the teletypes on what was not-yet the ARPAnet. A dozen colleges and a dozen military bases. (The "DNS" was a static one-page sheet on the wall.) We would look around their filesystems. Mostly looking for StarTrek, a teletype-oriented game of coordinates and firing power. Obviously this type activity would lead to Policy.
Note that my early hacks were before the age of unix. It existed but in a very small way and I doubt I encountered it. A couple years later it grew, and at that school too, but I had moved beyond such stuff.
For reference, what the real Comp Sci students were studying was PL/I. COBOL and Fortran were not considered growth fields, ALGOL 60 was just a student's toy; BASIC was just for high-schoolers.
Ah, PL/1. IBM’s attempt to conquer the world, combining FORTRAN and COBOL into one annoying package. The uni had several big IBM machines, possibly System/360s, it’s been a while, I don’t remember. We also had a Burroughs and a Prime, and a GA, which was fed punch cards. Note that the Burroughs was so slow and annoying that students used the GA, and punch cards, in preference. We did FORTRAN on the Prime and the GA, COBOL on the Burroughs and the GA, and PL/1 on the mainframe. C? What’s that? I think that C did show up my last year, alongside Pascal. I had Pascal on my Mac, not that I could do much, that was a Mac 128 and there wasn’t much memory to play with. And storage was 400kB floppies.
OK this one was feeble but in general I enjoy these and on a Monday my acceptance criteria is low so please keep posing them and I am willing to take the good with the bad.
I don't have any stories myself but I do know of someone who blew up the electronics of a significant instrument when at a antarctic research station at the beginning of winter with no possibility of repair for 10 months. This would have been a great Who? Me? but it is not for me to tell.
To be fair, these stories are up against some *really* tough opposition at the moment (we see you lurking there, Elon).
Any story sent in at the moment is going to feel like small change; fingers crossed that El Reg knows that and is holding back some good ones to use after we've regained our sense of normality. Please let be the case. Pretty please?
> the company got an important lesson in checking its documentation.
One that, if they are like every other company I have experienced, they continued to ignore.
After all, if you check (or test) something, that might turn up errors. Errors cause delays and they aren't in the release timetable.
I'm guessing they probably took a while (if ever) just to fix the error they found, if their company works anything like every place I've worked. I think the only thing about the Agile Manifesto that was understood by companies was the part where they say "We value working software over documentation". Usually, the policy ends up being "If the documentation bothers you, you change it. You can put whatever you like in there. Nobody will review your change until the new starter tries to use it for something.".
As someone who ends up writing a lot of documentation you never put passwords in the documents, refer to a (hopefully) controlled system. There are two reasons for this, the first is when someone updates the passwords the documentation doesn’t need to be rewritten, the second is if you shouldn’t use it then you shouldn’t have access to the password.
The other problem is someone changing the process from what the document says and not updating the document, so the process is as good as useless.
As someone who has spent a large amount of time on call for various jobs I know that good documentation is invaluable especially when having to fix something at 3am when you have just been woken up….
It's not complicated - it reeks. It stinks when the person sitting next to you is drinking a coffee at their desk. Beyond that, when you've got a corridor full of coffee binge drinkers (looking at you, university corridors), the smell has permeated the entire place and is inescapable.
So I care for the same reason that I'd rather not be sitting next to somebody vaping. Even if there's nothing harmful in it, I don't want to deal with your accoutrements stinking the place out.
Joke icon not needed :o)
My procedural documentation always has, after the "this is what this procedure covers" line, a warning "This document is intended for team X. If you are attempting this procedure and NOT a member of team X, STOP NOW, and contact a member of team X".
Minimum necessary permissioning is a good principle, but isn't always applied, so if someone's using my procedure and buggers things up, they can't say they weren't warned.
large letters. Like written for a 6-year old
6 year old me had no issues deciphering small letters, its the older version of myself that requires large letters (or lenses). Panic will although be less an issue than the enticing lure of sweeping the problem under the carpet to be allowed to go back to sleep.
I'd go for "Think before you act" instead of "DON'T PANIC".
I remember an old colleague telling me a story (so it may be apocryphal) of a company who had a written procedure for a delicate task. It was the kind of task that only got done when things were going VERY pear shaped, and it had been about 3 years since the last time t had been needed.
My old colleague, then just a junior PFY, dutifully went and obtained the procedure from the guide, and started to follow the steps precisely, as he had been instructed to do. About 2/3 of the way through he went to visit his boss and asked who Dave ********* was? His boss looked at him funnily, and told him to stop being a troublemaker and get back to work. My colleague returned to his desk collected the guide, returned to his boss, and told him he was stuck on Step 24.
The Boss grumbled, scanned down the page, and upon reaching Step 24, proceeded to turn white as a sheet, and mouth something along the lines of "Oh Sh%t!". The Instruction read something along the lines of "For the Password to System X, please contact Dave *********."
Apparently, this Dave had left the company about 18 months before, and it had not been a happy breakup. So the chances of getting the password were Zero.
I dont remember, what my old colleague said happened, apart from a lot of wailing and gnashing of teeth, but he and the company learnt a valuable lesson. Never entrust sensitive information to a single person. And better yet, dont entrust it to a person at all, but use a safe (or for the modern case), a password locker.
I was at a site where they were walking through the Disaster recovery scenario.
The big red switch to do something was in a locked cabinet (with reinforced glass). Come the moment of pressing the big red switch it was suddenly "where's Helen?" .. the manager with the key... She was in the bathroom feeling not very well. Someone had to go to the ladies loo and the key was passed under the door!
I was a "Dave" (not the "Dave" in the story though).
Had left the company a few years ago and had a phone call asking if I remember what the password was for the stock control server was.
As she was very nice while I worked there, I did sort of help her - (was it Password, password, PassWord - something like that??) Had it been the MD that called, then I would have complete memory loss...
* It wasn't actually password - different word, can't remember what now!!
I had one of those calls. It must have been especially embarrassing for them as we didn't part on good terms, and they'd ended up paying me a fair bit of money at the suggestion of my solicitor! I didn't particularly feel like helping, but as it happens, I didn't remember the password they wanted anyway. It wasn't either of the two* passwords that every customer system we supported used one of, for our admin level account.
* there were two passwords because at some point somebody had finally realised that the then only password, "ynot", being our MD's name backwards, was a bit insecure now we were setting up remote access to their systems. (The new one was reasonable, albeit overused.)
Documentation that does not match reality is worse than lying, it's outright FRAUD.
Select "bulk import", select "Choose file"....
THERE
IS
NO
'CHOOSE FILE'
OPTION!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
One of these days I'm going to visit London, find the people responsible for our software and educate them with a two-by-four. There. Will. Be. Blood.
I've put passwords in documentation for pre-installed demo systems. You know the kind of thing you fire up once as a developer, play around with and then destroy. Fortunately, these demo systems never, ever get deployed in a production environment. And if anyone is so stupid to do so, then they would immediately change the passwords right?
You mean like Oracle Scott/Tiger? Yes, I went to a customer to tidy up a mess left by a previous contractor; and that was still in their production system. It contained customer personal details, discount structures, company financials, etc. All the staff used that login, and (as I remember?) it had been in use for about 5 years.
My first rule would be, don't give superuser access to anybody that doesn't understand the commands they are typing.
Yes, I know in theory, you can have a documented procedure and give the job to a simpleton who simply follows that procedure to the letter. I've worked in places where they do that.
I know people whose first response in any situation is to pull out the notes from a 2 day training course and follow the instructions they were given 5 years ago by a tutor who has probably never actually done it themselves. It's great for people who work in the kind of organisations where everybody needs to keep their head down and their arse covered at all times.
But things can go bad very quickly when something unexpected happens that doesn't match the documentation. IMHO It's better to employ somebody that actually understands the system inside and out and doesn't need to read a manual to know what to do.
I read through instructions before starting to discover what I will need before I get there. And in documentation I /write/, the first paragraph is a list of the things you will need later on. Get user's name and birthday. Prepare username in this format, prepare password in this format, prepare email address in this format. Prepare display name in this format. etc. /Then/ the rest of the instructions.
From the article, this particular set of instructions were not supposed to include the superuser login details. They were instead a result of copy/pasting from a set of instructions for performing a backup.
Although that does then beg the question, of why there wasn't a separate backup user?
Years ago, we were used to have scripts for data backups in our DC, with quite impressing mirror copy stuff, until we had high end storage with those included.
So, a decade later, my then boss was called by the people (same company) from DC ops at the other end of the world.
The script failed, can you help ?
We discovered the script was acquired by the clueless people there and run for years to perform backups, without our team even knowing anything about the environment or its use.
And, as the last updater's name was my then boss they called him in ... He laughed a lot and politely explained support was on them ...
I was working as a software pre-sales 'droid for what was once a proud hardware company in the 70's, before it pivoted to a bit of an also ran software company by the time we were in the 90's. Regardless they did have a rather fancy, if temperamental, piece of configuration / BoM software. So being tasked with setting up said software for a customer demo I diligently followed the manual; no joy. I asked my boss for advice, he suggested liaising with the regional pre-sales lead, who said "follow the manual". Eventually, got the name of the global lead for this piece of software. I carefully explained all the steps I had gone through, and emphasised that I had followed the manual at each and every turn, his response "Ahh yes .. but what you must understand is, the manual lies!"
Never a truer word!
Trying to set up a fediverse instance this week.. Start with a fresh and up to date install of Ubuntu each time.. I tried four different software setups, follow the setup scripts to the letter. Every one failed somewhere along the line. I managed to solve some of the issues, but it wasn't until I tried the very latest version of mastodon, released after I'd started this exercise, that I finally got the bloody thing working, and at that, it had told me to install the wrong version of Ruby than it then required later on.
At a time long, long ago, I worked for an outfit and administered a system which was critical to production. I had produced a set of diagrams, notes and other instructions on how the Beast worked. Which servers were where and what to do in the event of a system crash. These were contained neatly in a three-ring binder on a bookshelf over my desk.
Our IT department, always looking to expand their baliwick, asked that they be given access to these notes. Just in case I was unreachable, hit by a bus or some such thing when the system went down.
"Will a Xerox copy do?" I asked.
"How about you just save a document on one of your servers", was the reply.
"Oh, you mean the crashed server that you are attempting to bring back on line? Think about that for a sec. At least with a hard copy, you can read it with a flashlight while trying to find the main breaker."
And they let these people run around with floppy disks ...
is rather more mechanical than IT based, the need for documentation is rather more critical.
The need for readable documentation is even more so
The need for the engineers to read the readable documentation even even more so.
After a recent disaster.....
"Did you follow the setup document?"
"Yes"
"What about the bit for checking clearance between the robot arm and the fixture?"
"What bit?"
"The bit written at the top of the document saying 'RUN IN SLOW MOTION AND CHECK FOR POSSIBLE COLLISIONS' "
"Errrrrr......."
I dont know why I bother sometimes
I have a vacuum/mop robot.
First use of the vacuum/mop - has difficulty mapping the room, so I consult FAQ, Dr Google and finally ring tech support. "It says quite clearly to clean the lidar before you use it" - "mate I am looking at the paper and a pdf version of the manual on your website - I have done a search for lidar and gone to each reference, could you point to the exact page and line where I am told to do this and the instructions for doing same?" -
tappity tap tap tap, "er, um , er - look er open up the manual for the window cleaner model xxxx it uses the same lidar setup".
Perform cleaning step & all good
This post has been deleted by its author
I liked DEC VMS. MS DOS (and later, Windows and NT), not so much >>=======>
I wonder if the company mottos may have given us hints as to why that might be? Digital Equipment Corporation's was 'Honesty and respect for customers and employees'. Microsoft's, at a similar time, was 'A computer on every desk and in every home, running Microsoft software’.
In about 1985 our Microsoft rep, over a boozy lunch, thought Bill had said "A hundred dollars a year from everybody".
DEC had a bad case of "firstest with the mostest" which was great in the beginning but produced a culture of corporate arrogance, of the "we don't use standards, we are the standard" variety. They were not ready for the rise of Unix or the advent of the PC clone. They were not alone: several of the "workstation" mini-computer companies just couldn't let go of their proprietary systems, not to mention their huge markups.
...that few are qualified to practise.
I speak from the depths of yet another design doc that tries its hardest to be everything but. Discursive, digressive, talking about what things are not instead of what they are....
And don't get me started on those "look how smart we are" documents.
But let us also ask why that ever larger tome called "Your car and its features" is 98% warnings and 2% stuff you need to know.
The Register 
Biting the hand that feeds IT
Copyright. All rights reserved © 1998–2025
