One could write down what knowledge a user has gained in a word document or even a wiki. Both will one day be filed and/or forgotten. Perhaps something like the Bayeaux Tapestry or Egyptian hieroglyphs would be better?
I will be retiring at the end of next year from a 39 years position. I am trying to document all the procedures I have set-up along all these years, this is a very unpleasant work.
Unpleasant but admirable on your part. Anyone else would have given up caring and spent the last six months flicking pencils around instead. I know someone whose annual contract renewal is in limbo because the HR person in charge of salaries retired with giving a fuck about documenting such things.
And I really hope your work is apreciated by at least one person. My personal experience is that nobody reads any documentation, not because there isn't any but there is too much (in volume) of it and nobody has the time and patience (this is the 21th century, remember ?) to spend hours reading (maybe) important stuff.
PS: I had to document our mostly manual software image build system (because I built it) and at least 2 software engineers reviewed it and a third did read it in details (while not in its entirety)... because he had to design the successor system ;-). So at least my work was not entirely wasted. Needless to say the manager who made me writing the documentation did not even glance at it when it was declared "finished".
Oct 14, 2023·edited Oct 14, 2023Liked by Alistair Dabbs
At one site, I wrote a "Surviving <sitename>" document, aimed at those providing holiday cover, because I was the only resident tech.
It listed things like documentation needed to get on site, where my desk was, where the server room was and how to get in, who to talk to in order to access the sealed envelope of master passwords, and important phone numbers. The locals were friendly, but there were Health & Safety musts (my desk was next to H&S). There was advice about catering (the canteen was decent; yes you can use the coffee in my drawer). There was advice about visiting some dangerous areas - someone will come out and guide you, because you are there to sort out their problem. There were even descriptions of common faults and how to fix them quickly.
More than one visiting tech returned to their own site and wrote similar.
I finally upgraded from Windows to Debian, along with setting up virt-manager (and GPU passthrough!) to set up numerous “legacy” VMs to run several old Windows and Hackintosh environments. Since every step forward had been preceded by at least 5 false steps in completely wrong directions, out of necessity I wrote myself TEN “how-to” documents, each more than a couple pages in length, numbered in sequential order, and giving idiot-level instructions of precisely how to rebuild the environment starting from a freshly-formatted drive.
(Because the next time I even look at them, I will have completely forgot everything described, because I literally just do not give a damn about remembering even the tiniest fragment of any of this krap.)
But then software isn’t always bought because of easy-of-use, it’s bought because of vendor/cost and at times the end-user is never considered, nor the operational cost of training.
Even with written documentation, I’ve found the vendor providing ‘“latest release” screenshots taken from software that we buried six feet deep 10 years ago and their product has had GUI framework updates or whole colour scheme changes in the latest release.
“Just where the HELL have they moved the cancel button to now?”
“The clickable link now cancels this input? Eh? Why did they drop the cancel button that was obvious? It’s not like we’re running our screen display to squish in a button, damn it. Tell them their 1995 era software with a year 2000 web interface needs a good kicking by some burly blokes behind the bike shed, and the vendor better not be looking for a praise in their online reviews.”
I’ve taught classes on software use, taken vendors through a wild review of their on tool in production, shimmied all sorts of stuff together to make things work, cried with users of the systems, recommended software tools with million dollar budgets but rarely actually seen the fabled user-led development of software/processes in practice. Long may it continue. I’ve got 15 years to retirement, I need something to between now and then.
Let them make it up as they go along, let them teach the new acolyte by oral tradition. The rest of us can spend eternity saying ‘Is that process documented anywhere?”
Oh yes, the out-of-date screenshots, I see them everywhere. One of the Adobe certification exams I took presented me with a screenshot that was not only out of date but had been been grabbed from an old beta version of the program and did not actually exist in the public release of the software.
The lack of documentation is a constant modern problem. I have just spent the afternoon trying to configure a firewall cluster on aws. The Cisco docs were actually useful and we managed to get the firewalls up in a couple of hours, the AWS documentation a lot of the time it is a losing battle of random web pages and contradictory information.
Oct 13, 2023·edited Oct 14, 2023Liked by Alistair Dabbs
Forgot to mention any video made of how to do something on aws is only valid for the few weeks before the screens are revamped to make them new and shinier….
Our company updated its provider handling company credit-card disbursements. This seemingly simple task, and previously it was extremely simple, moved from paper to on-line via the provider bank (lets give it a pseudonym of National Eastminster). It was a rubbish menu full of traps which ejected you from the application. For security, there was no written procedure. For security, your access password had to be changed every month and if you didn't log in every week you were shunned and had to order a new password with 2F authorisation. No-one would use their personal mobile phone for this scenario so I ended up being the recipient of dozens of colleagues' 2nd-factor on my work mobile.
We had training, which lasted 2-3 minutes, where the 'trainer' (boss's PA) demonstrated the technique on her PC. Of course, we didn't have the same access rights so at first nothing worked.
I stopped using the credit card altogether and ordered someone else to buy things for me (typically from RS or Farnell).
When I left, I handed over the phone (switched off) and I have no idea how the unfortunates ever got onto the system again.
We just had a "basic" and an "advanced" training on Jira and Confluence, given by one of our core super users of said tools. Using Skype, to an audience of 60+ people...
I don't know, the worst combination of "frontal education" shunned by schools since the 2000s, with the near-inability to ask questions while the tutor was going through the motions of clicking, searching, trying to explain the idiosyncrasies of the GUIs of said tools and the necessary workarounds.
At the few question times during the 1h "training" of course nobody had any, so at the end I asked the question why with my account I could not even do the first task which he had shown at the very beginning.
There was a satisfactory answer, but the whole things was ridiculous: If you tried to follow the training on your own PC/login, you missed important pieces of the presentation, if you did just stare at the presenter's screen, you wouldn't know that even the first thing did not work for you.
tl;dr: Some trainings seem to be just corporate "check the box" events, so the company could claim you were trained, and therefore any problems you face must be your own short comings.
Oct 14, 2023·edited Oct 14, 2023Liked by Alistair Dabbs
Sometimes the training is just pitched at the wrong level.
I've seen people trying to teach MS Office to users who were new to Windows and had never used a mouse before.
For one contract, were were forced to get Compaq's "Server" qualification. To qualify for the 2 days' "training" you had to complete their 3 day "Desktops & laptops" course.
The "exams" for these were multiple-choice, and were "open book" to ensure you couldn't fail.
I knew more than the trainers did.
But I did get the official Compaq Screwdriver, and five decent lunches, on the company!
At another place I was downgraded at my annual review for not taking up the one day training on Windows XP. I pointed out that the training was aimed at end users; it would have been a three hour drive each way, and that I had already been supporting it at work for 3 months, and had been using it, and the matching server, at home for the previous two years. Add in the fact that I would have to catch up on the job queue when I returned, and it had been a no-brainer for me. But management were ticking their "personal development" box., and anything which I might actually find useful cost too much.
I fondly remember writing up an admin guide for Office 365 for the basic functions the guys supporting it might need at the end of a 4 month contract. My first words were "these screenshots might not look right in a few months, as Microsoft rolls out changes frequently". I was correct, almost none of the screenshots I'd taken the week before were accurate anymore.
"f you are the type of employer who" should be "employee" methinks.
I've spent years of using (or ignoring) bad documentation, and occasionally being forced into the mind-numbing job of writing it.
I found that the best way to come up with anything remotely useful, is by writing your own documentation when you are learning something new. When teaching it to others later, share the documents and let them add and improve on it.
Of course, after a few years it is hopelessly outdated anyway.
One could write down what knowledge a user has gained in a word document or even a wiki. Both will one day be filed and/or forgotten. Perhaps something like the Bayeaux Tapestry or Egyptian hieroglyphs would be better?
I will be retiring at the end of next year from a 39 years position. I am trying to document all the procedures I have set-up along all these years, this is a very unpleasant work.
Unpleasant but admirable on your part. Anyone else would have given up caring and spent the last six months flicking pencils around instead. I know someone whose annual contract renewal is in limbo because the HR person in charge of salaries retired with giving a fuck about documenting such things.
And I really hope your work is apreciated by at least one person. My personal experience is that nobody reads any documentation, not because there isn't any but there is too much (in volume) of it and nobody has the time and patience (this is the 21th century, remember ?) to spend hours reading (maybe) important stuff.
PS: I had to document our mostly manual software image build system (because I built it) and at least 2 software engineers reviewed it and a third did read it in details (while not in its entirety)... because he had to design the successor system ;-). So at least my work was not entirely wasted. Needless to say the manager who made me writing the documentation did not even glance at it when it was declared "finished".
At one site, I wrote a "Surviving <sitename>" document, aimed at those providing holiday cover, because I was the only resident tech.
It listed things like documentation needed to get on site, where my desk was, where the server room was and how to get in, who to talk to in order to access the sealed envelope of master passwords, and important phone numbers. The locals were friendly, but there were Health & Safety musts (my desk was next to H&S). There was advice about catering (the canteen was decent; yes you can use the coffee in my drawer). There was advice about visiting some dangerous areas - someone will come out and guide you, because you are there to sort out their problem. There were even descriptions of common faults and how to fix them quickly.
More than one visiting tech returned to their own site and wrote similar.
I finally upgraded from Windows to Debian, along with setting up virt-manager (and GPU passthrough!) to set up numerous “legacy” VMs to run several old Windows and Hackintosh environments. Since every step forward had been preceded by at least 5 false steps in completely wrong directions, out of necessity I wrote myself TEN “how-to” documents, each more than a couple pages in length, numbered in sequential order, and giving idiot-level instructions of precisely how to rebuild the environment starting from a freshly-formatted drive.
(Because the next time I even look at them, I will have completely forgot everything described, because I literally just do not give a damn about remembering even the tiniest fragment of any of this krap.)
But then software isn’t always bought because of easy-of-use, it’s bought because of vendor/cost and at times the end-user is never considered, nor the operational cost of training.
Even with written documentation, I’ve found the vendor providing ‘“latest release” screenshots taken from software that we buried six feet deep 10 years ago and their product has had GUI framework updates or whole colour scheme changes in the latest release.
“Just where the HELL have they moved the cancel button to now?”
“The clickable link now cancels this input? Eh? Why did they drop the cancel button that was obvious? It’s not like we’re running our screen display to squish in a button, damn it. Tell them their 1995 era software with a year 2000 web interface needs a good kicking by some burly blokes behind the bike shed, and the vendor better not be looking for a praise in their online reviews.”
I’ve taught classes on software use, taken vendors through a wild review of their on tool in production, shimmied all sorts of stuff together to make things work, cried with users of the systems, recommended software tools with million dollar budgets but rarely actually seen the fabled user-led development of software/processes in practice. Long may it continue. I’ve got 15 years to retirement, I need something to between now and then.
Let them make it up as they go along, let them teach the new acolyte by oral tradition. The rest of us can spend eternity saying ‘Is that process documented anywhere?”
Oh yes, the out-of-date screenshots, I see them everywhere. One of the Adobe certification exams I took presented me with a screenshot that was not only out of date but had been been grabbed from an old beta version of the program and did not actually exist in the public release of the software.
The lack of documentation is a constant modern problem. I have just spent the afternoon trying to configure a firewall cluster on aws. The Cisco docs were actually useful and we managed to get the firewalls up in a couple of hours, the AWS documentation a lot of the time it is a losing battle of random web pages and contradictory information.
Forgot to mention any video made of how to do something on aws is only valid for the few weeks before the screens are revamped to make them new and shinier….
Our company updated its provider handling company credit-card disbursements. This seemingly simple task, and previously it was extremely simple, moved from paper to on-line via the provider bank (lets give it a pseudonym of National Eastminster). It was a rubbish menu full of traps which ejected you from the application. For security, there was no written procedure. For security, your access password had to be changed every month and if you didn't log in every week you were shunned and had to order a new password with 2F authorisation. No-one would use their personal mobile phone for this scenario so I ended up being the recipient of dozens of colleagues' 2nd-factor on my work mobile.
We had training, which lasted 2-3 minutes, where the 'trainer' (boss's PA) demonstrated the technique on her PC. Of course, we didn't have the same access rights so at first nothing worked.
I stopped using the credit card altogether and ordered someone else to buy things for me (typically from RS or Farnell).
When I left, I handed over the phone (switched off) and I have no idea how the unfortunates ever got onto the system again.
Proposed title for your new shonen harem manga, Mr Dabbs:
"100% IT Trainer DxD"
We just had a "basic" and an "advanced" training on Jira and Confluence, given by one of our core super users of said tools. Using Skype, to an audience of 60+ people...
I don't know, the worst combination of "frontal education" shunned by schools since the 2000s, with the near-inability to ask questions while the tutor was going through the motions of clicking, searching, trying to explain the idiosyncrasies of the GUIs of said tools and the necessary workarounds.
At the few question times during the 1h "training" of course nobody had any, so at the end I asked the question why with my account I could not even do the first task which he had shown at the very beginning.
There was a satisfactory answer, but the whole things was ridiculous: If you tried to follow the training on your own PC/login, you missed important pieces of the presentation, if you did just stare at the presenter's screen, you wouldn't know that even the first thing did not work for you.
tl;dr: Some trainings seem to be just corporate "check the box" events, so the company could claim you were trained, and therefore any problems you face must be your own short comings.
Sometimes the training is just pitched at the wrong level.
I've seen people trying to teach MS Office to users who were new to Windows and had never used a mouse before.
For one contract, were were forced to get Compaq's "Server" qualification. To qualify for the 2 days' "training" you had to complete their 3 day "Desktops & laptops" course.
The "exams" for these were multiple-choice, and were "open book" to ensure you couldn't fail.
I knew more than the trainers did.
But I did get the official Compaq Screwdriver, and five decent lunches, on the company!
At another place I was downgraded at my annual review for not taking up the one day training on Windows XP. I pointed out that the training was aimed at end users; it would have been a three hour drive each way, and that I had already been supporting it at work for 3 months, and had been using it, and the matching server, at home for the previous two years. Add in the fact that I would have to catch up on the job queue when I returned, and it had been a no-brainer for me. But management were ticking their "personal development" box., and anything which I might actually find useful cost too much.
"ph'nglui mglw'nafh Cthulhu R'lyeh wgah'nagl fhtagn"
Would this be Copper Cthulhu? https://autosaveisforwimps.substack.com/p/copper-cthulu-has-invaded-my-house
I fondly remember writing up an admin guide for Office 365 for the basic functions the guys supporting it might need at the end of a 4 month contract. My first words were "these screenshots might not look right in a few months, as Microsoft rolls out changes frequently". I was correct, almost none of the screenshots I'd taken the week before were accurate anymore.
"f you are the type of employer who" should be "employee" methinks.
I've spent years of using (or ignoring) bad documentation, and occasionally being forced into the mind-numbing job of writing it.
I found that the best way to come up with anything remotely useful, is by writing your own documentation when you are learning something new. When teaching it to others later, share the documents and let them add and improve on it.
Of course, after a few years it is hopelessly outdated anyway.
Cudos for the Blade Runner fragment!