Why should I learn by ORAL tradition? Where's the DOCUMENTATION?

Just be glad

theres anyone with any idea how the system works at all

Our collective nightmare here at Roach towers is the legacy of robot programs created in the mists of time by the aforemention long departed employees... that have absolutly no documentation with them.

No datum points, no special tools, no fixturing, in fact, we're not even sure we still have the machine it was created for.

Then the job surfaces again, taken on by a foolish management convinced we can do it cheaper than our rivals because its been done before, and it makes its way to the shop floor, whereupon its greeted with "f*** me, this job went obsolete years ago".

And an unlucky employee gets it after the more skilled (and more aware employees have taken the day off sick/ gone down the pub/hidden in the toilet crying), and after morning of head scratching and puzzling has given up on the legacy software and decided to write a new program

This takes time of course.

This alerts the management who become enraged.

Its at this point the rest of the employees disappear into various hidey holes as yet undiscovered by the management leaving the unlucky guy who doing the job all alone on the shop floor to face the rage of the management......

On the good side though is the sure knowledge that due to the cost of making the part this time, we'll never see it again, even if it does have a spiffy new program with documentation, all written by a recent ex-employee

Training? Chance would be a fine thing.

Here's this new system we've mentioned obliquley on the intranet pages. Some people have had training, but most of you haven't, unless you work in the golden sectors, where we've trained everyone and given them an ipad as well.

No, you can't use the old system as we've promised the partner agency that we're not going to use it any more.

Yes, I know it's 4am. Yes, I know that neither you or your supervisors even knew how to open it, let alone use it, but we're going to insist anyway. Oh, and don't get it wrong, otherwise it'll be noticed and passed to your senior managers to reprimand you about it and, if you're lucky, we might ring you up shortly after you've got to sleep to explain that it's wrong, and then hang up before telling you how to do it properly.

The only thing better than a weird CMS ...

... loads of them! Some obscure Notes databases, all different in format. Some wikis, many of which are on barely remember servers under desks. A "company wide" intranet CMS, that is actually less useful than any of the former but is delusionally considered by its adherents to be "the single source of corporate truth". Various "portals" with widely varying degrees of usefulness, timeliness and general synchronisation with other sources, for different customers. Entirely separate change control, bug tracking, version control, risk and issue management systems; usually (several) more than one of each, sometimes on single projects.

One or two systems that are RSS enabled, far too many that spam you with email notifications, and far too many where, unless you set aside an hour a week to visit them all, you won't know that anyone has changed them. Sorry for ranting, Dabbsy, but you've hit a bit of a nerve.

Been there myself, though..

Sometimes you just try to fix a small problem by putting some glue code between or around things that otherwise don't get along that well, and it lessens your workload.

The problem is that solving one problem allows the idiots around you to come up with new ones. Which you need to bolt on to the original code, which was (as all quick fixes) just glue without addressing the fundamentals because those are either untouchable or are the equivalent of a house of cards in a rock concert (misplaced and unstable). Your quick fix has now turned into a self perpetuating horror, because you solved THAT problem, so it surely should not be that much work to solve THOSE as well (ad infinitum). Documentation tends to fall by the wayside as you try to keep up with the avalanche you just started. The annoying thing is that experience is the thing you get AFTER you get yourself in trouble..

That's why the most important lesson for any prospective sysadmin is the ability to say "no". Even if they can't tell C# from a cage nut - if they can do that, you're winning.

CMS on superdome

Anon, for obvious reasons.

There was this shite application, hacked with Oracle IAS V1. The whole sheebang: bypassed APIs, check, works only by sheer miracle and unspeakable hacks, while Oracle had said it was not possible, check, can't be moved to a system with another IP or hostname, check.

As a result, it was preventing a full HP Superdome 64 to be decommissioned, as it was on one of this guy's partition, the app was running. It could easily have fitted on one SD CPU + 5 GB.

I think for 2 years, this SD ran this thing alone, before another app was created.

One size fits all

The problem with general office product training is that it is often a "one size fits all". So you sit in a classroom being told to press this key and that key like a bunch of robots. It turns out that was how the lecturer was trained too. The idea that they perhaps should understand the concepts too is met with a blank look and "I'm not technical".

Then the whole thing gets held up because someone can't find the key marked "any".

Just Soft Skills

I've worked for large corporate IT Service Companies in the past...

They tend to be generous when it comes to soft skills training, but fairly random when it comes to technical training in my experience.

When they do, it's either a year before you get to revisit the platform (by which time you've forgotten everything and can't find the nice manuals you got given) or its a platform they don't use, had not intention of using and is more obscure than 70's cult Tv to todays twenty somethings.

Catch-22

The best training courses are the ones you go one after you've scrabbled about with the product yourself for a while. Assuming you then have a lecturer who knows the product inside out - then your mind does not get clogged up after the first couple of days. Better still you really appreciate what the lecturer is distilling from their experience on the finer points.

The lecturer also has to command respect - so that when they want to halt a particular line of increasingly esoteric questions then the class complies happily.

Most importantly you then need to put the training to practical use as soon as possible afterwards.

The problem with many training courses is that people are sent on them totally cold - and they don't get to use the knowledge in anger for a long time afterwards.

In my experience a lot of the pre-emptive training was in the wrong things. When new knowledge was suddenly a pressing need - it was often a case of "here's one I made earlier" - in my own time, at my own expense - purely out of technical curiosity.

Ah... training... oh happy, happy, joy, joy.

Around here, the troops on the floor go into a training room where an instructor versed in the software spends several days with them with actual hands on training along with some docs and cheat sheets.

For the support troops... we get a video conference for a couple of hours of watching some idiot move his mouse around the screen going: "click here", "do this"... We end up wondering what the purpose of this software is and what it really does.

The end result, the users know how more about the damn software than the support team. Bah....

Oh why this hatred for records?

Agree on bad training regimes, but this:

As a result, learning how to use one of the most important software systems at the company has become an oral tradition passed from one hapless employee to the next. When a casual shift worker turns up for the first time, he must approach the Tent Cubicle of the CMS Elders and sit around a campfire to hear a wizened office Gandalf recite obscure GREP expressions from cultural memory.

... perfectly describes our residential strata Council's approach to recordkeeping.

Meeting minutes? Records of votes by Council? Records of how a $30,000 purchase was initiated and approved? Records of near lawsuits averted at the last possible second? Reports on engineering studies indicating repairs needed in the hundreds of thousands of dollars?

Those that exist are so obscure and hard to access that they are of no use in tracking anything.

Instead we rely on a long, arbitrary, contradictory and (I suspect) made up on the spot list of rules that all must follow but which exist only in the minds of the person speaking them.

All of which is a roundabout way of saying: when you see bad documentation and a lack of training you need to first ask, "Who benefits from this?"

Because someone always does, and if you can identify them you can find a solution.

I used to work for a large company that was glad to bring teacher-contractors in-house to teach courses we needed. The only trouble was they would insist that a 5 day course be presented in 3 days, and a 10 day course in 5 days. At the end of the course our heads were spinning, but the bean counters were happy.

Training?

As someone who has the dubious pleasure of producing some of our software company's training materials I was of course delighted when a "senior" product person said the following. "We don't need to bother with training, our software is so intuitive that anyone can understand it".

Strangely our customers (and internal staff) beg to differ. ;-)

The best thing about training

is living in a hotel for a week and eating food on expenses.

The so called training I could do without.

Monday - start 10am. Instructor does the "ice breaker" and tells you where the fire exits are, by which time it's time for lunch. Bugger off at 4pm.

Tuesday to Thursday inclusive - turn up late, watch lowest common denominator PowerPoint, bugger off early.

Friday - half day.

I'd rather they give me a week's paid leave so I can sit in a conference room with a book, I'm sure that's better value for money.

This may have the unfortunate side-effect of immortalising the Dabbsy name

there once was an old man called Dabbs

Who's pubes were infested with crabs

his de-lousing attempts were all met with strife,

until half life wife decided the answer was a knife

The users groan?

I'm lucky if I get my IT team to freshen up, let alone the users.

BTW, LOVE the Blade Runner clip!!!! 2 thumbs up.

I am the only person in the (small) company versed in a key piece of software. 13 years of using it and occasionally tweaking it are my only credentials.

If anything did happen to me, the others could get by for a bit until a change is required, and worse case any database expert brought in could do it.

Now I suppose I need to add to the documentation. Bugger.

In my experience documentation has several problems.

Number one is expressed by the ubiquitous use of "RTFM". This suggests that often it doesn't get read - no matter how good.

If written by the developer it might assume there is only their way of doing something - so it doesn't need further explanation. If written by a technical author they don't always convey the subtlety of the developers' meaning of words - at worst they don't grasp the importance.***

Lastly - documentation gets out of date. The more precise its starts out to be - the more likely it will be wrong, or contradictory, in a particular detail later.

When I was a junior on a new operating system there were weekly updates to the bookcase of comprehensive thick manuals. Usually there were sheets of instructions to alter just a word here and there with a pen - possibly there might be a replacement page or two. As the manuals were not important to our role we just added the updates to a pile. Every few months they would re-issue a whole manual's updated content - so we could then put that in the old ring binder in one easy action.

***the local council's plastic recycling notice says "remove bottle tops". What is unclear is whether they mean "discard" as non-recyclable - or merely "separate" for reasons of sorting.

Definition of " Expert" in any subject...

...someone who has learned from making all the mistakes.

Imaginary manuals

Just a few days since I opined that "I must get round to reading the imaginary manuals" to my lead...

RTFM

I've spent many years training my team to use the latest bits of kit that get foisted onto us, usually with little or no training for any of us, even me.

Almost all the training I have ever been on has been too short, too hurried, too poorly structured to unerstand what to do after I've got back to the office and without any follow up after I've tried to use the stuff.

Where possible I spend time experimenting at the "What happens if I do this" level, which at least means that I get to understand what's going on.

What I seldom succeed at is using "TFM". Because I've yet to find one that worked in a logical way for the user.

All too frequently they begin with apparently simple stuff that actually makes no sense at all until you know what is in chapter 43. The writer obviously thought that chapter one was simple, but then he did know all about that stuff in chapter 43.

I don't think I've ever had a "FM" that starts off by saying what the software/device is trying to do and how it will do it. Which is fine if you were the person who went out to get the kit, for a job you know needs to be done. But of no use at all when you are one of the Poor Bloody Infantry who is given this stuff and told that we all have to use it now. So you are left pressing buttons and entering data with absolutely no idea why you have to put that bit of data there, why you can't put this data here, and so on.

At the end, if you wade through the first few chapters you will have an idea how to do the example task - but that will have had absolutely no resemblence to the work that you actually do.

The alternative scenario is the one where the training pack tells you how to do the blindingly obvious stuff. But as soon as you stray from that path to try to do what you actually need to do there is nothing.

Example, an enormous hi-tech networked printer/copier/fax machine with clear instructions how to create new user accounts, which corresponded to the interface saying "accounts" followed by- "New".

But then absolutely no guidance how to change the users' passwords from the default, create individual mailboxes to store documents for printing later etc. None of which appear in any of the menus or the index of the manual i.e. all the advanced stuff that the printer had apparently been chosen for.

Free training

If nothing else, I tell them, you can pick up a load of free training before ditching this joint and finding better paid employment elsewhere.

This is exactly what came to my mind last week!

The problems with training in new technology

is that it's an inter-company game of "chicken". Witness SAP in the 90s and the interminable training course structure. If one or two companies / government agencies paid for all their staff to get trained, they would invariably get "poached" by other companies / agencies and the benefit of that training would be lost. So the company / agency goes into the foetal position on training and no-one gets any more, ever again.

Anon for obvious reasons ...

We have to use some dire bits of software, which are universally hated by all staff - except the complete and utter ${expletive} who wrote it and thinks it's the best thing since sliced bread. There are off the shelf ticketing systems that work, yet we persist with this pile of manure.

Actually that's not quite fair (describing "it" as "a" pile of manure), rather than fix issues in said pile of manure, what usually happens is that a new one it written - equally manure, but different. Only it doesn't quite do what the old system does - so now we have two broken systems to work with.

Rinse and repeat.

To give some idea on the quality of documentation, an ex employee suggested I keep in hand the retort "I'll document my systems when you show me the user manual for ${system}" for next time the ${expletive} has a go at me. Yes, there is no manual whatsoever, no crib sheets, absolutely nothing. Yes the same ${expletive} feels free to have a go at others for not documenting stuff - it's great being able to turn round and say "so you didn't read my documentation stored on ${other crap system we have}" then. Actually ${expletive} isn't the worst - only the second worst after the boss.

The single biggest complaint I have about many even popular/mature open source projects (and the one that always instantly puts me off using them) is that you go to the official website and find it completely assumes you've already been using it for years. All there is is some cryptic change list and literally no information about how to start using it or even what it does.