Techie traveled 4 hours to fix software that worked perfectly until a new hire used it The trek through the working week can be long and tiring, which is why The Register always offers a little Friday morning refresher in the form of On Call – the reader-contributed column in which you share tech support stories. This week, meet a reader we'll Regomize as "Ray" who told us about his experience developing a sales …
As a tester I got a reputation for breaking things. I was always impatient, and would multi task ( use two windows) when one of the tools was slow.
We had to use a new tool for entering what you had achieved over the year. Because there was no save button, I assumed, like Gmail, it had autosave. I submitted it to my boss who said it was empty.
I did it again...and again it was empty.
I contacted the help desk, who asked "did you press the save button?" me:"I don't have a save button"... "Did you press the help button ?" "I dont have a help button"
If you run the application full screen, all of the buttons appeared, if you run it in a narrow window, all of the buttons disappear.
With all of their testing they naturally used full screen, so naturally didn't find any problems.
I had a call with the development team, and mentioned the 50 "defects" I found. Such as
me:"there is an icon with 3 small circles - what does it mean? There is no hover text, and it is not mentioned in the help"
them: "It is meant to be obvious...",
me "well it has failed - so what does it mean".
them: "err we don't know"
me:"The fonts you use are not dyslexia friendly, and the fonts are too small and not changeable"
them "Err"
me: "Grey text on a grey background is not easy to read in a well lit area " ....
A laptop with a small screen was always in my arsenal. I used to run on a large screen and the small screen concurrently and see that they had the same functionality. Surprisingly not in many cases, as demonstrated by the OP above!
This is a pattern that Micros**t could do with adopting!
I actually already have that (well, 43", actually meant for surveillance so it has 4 HDMI inputs, 1 DisplayPort and 1 USB-C), and that demonstrates another annoying problem: try to get your Windows, er, windows back in a sane place when you disconnect. If you don't know the Alt-Spacebar, M trick to get your window moving with the cursor keys you're in for a lot of fun, because restarting the app will show you that the (now erroneous) window placement is persistent.
No such issues on MacOS, btw, not tried it with Linux yet but my expectation is that there too sanity will prevail.
I’ve found windows 11 much better for this. In general once it’s ‘seen’ a particular input combination it’s fine once it sees it again.
However the newer trend of windows without an Alt-space menu makes the few remaining times it still happens much more annoying. (Signal, I’m looking at you).
"However the newer trend of windows without an Alt-space menu "
Yeah, one of the few CUI "artifacts" that still is mostly cross-platform too. Anyone removing stuff like that that has been around decades in multiple OS's and Desktops is total fucking moron! As per Liams /XLibre article, just because the "dev" doesn't use a function doesn't mean it's not something lots of other people use or even have a desperate need for, such as accessibility for those who can't use a mouse.
Er no, it's not PEBCAK. Windows is basically totally f****ing s**t at handling desktop changes.
Can't speak for Linux (or rather, any of the Linux supported desktop managers) as I don't (yet) use that. On a Mac, unplug a monitor, or multiple monitors (e.g. if you unplug a dock) and everything moves onto whatever desktop is left. Plug things back in, and everything (mostly) moves back to both the position and size it was (Apple Mail annoyingly doesn't put the message list columns back to their previous width).
Windows 10, carnage. Unplug a monitor/monitors - stuff (mostly) moves onto the desktop that's left (e.g. onto the laptop's built in screen which is (in desktop pixels) significantly smaller than the external monitor. Plug external monito(s) back in, everything jumps to the primary monitor, with smaller windows (they got reduced in size to fit the laptop screen) - and this includes stuff (like my Skype window) which I previously had on the laptop screen. Cue lots of cursing and manually putting everything back where it used to be. This is "especially irritating" when, as I had with a previous work laptop, when waking from display sleep - it thinks the external monitor has gone, resizes/repositions everything, then wakes the external display (or it's driver ?) up, so when you unlock the screen you find it all screwed up for the umpteenth time today.
Yes another function where "Windows is S**t" should be the sticker on the box.
> This is "especially irritating" when, as I had with a previous work laptop, when waking from display sleep
Ye Gods I hated that - along with a 2 minute screen lock that thankfully I had a registry hack (and use of Symantec AV's monitors and scripts) to disable it but still a pain after locking it to leave the desk
I haven't used it recently - banned at work at present - but "AutoHotkey" is a free scriptable Windows utility which amongst other things, can send messages to windows to control their position and size. For a situation of windows moving inconveniently, it could be used to run a script to move windows to pre-set places where you want them to appear. Mainly it's designed to turn keystrokes into one more more different keystrokes, i.e. macros, but it also can be made to run a script of actions once and terminate, or to sleep a few seconds or until the PC is idle, then execute the same actions again. Again, when I last saw it, its scripting language was tricky.
To be fair, that’s more about bad programming as much as bad OS behaviour.
It’s trivial to check if your main window placement is within the current available desktop bounds, and if not, set it to start up centred on the current desktop. But too many developers make too many lazy assumptions about the hardware the software will be used on.
haven't got the desk space for something that large. 22 inch monitor currently there takes up most of the free space together with non working power supplies i haven't gotten rid of yet, disks from old non working computers that need to be erased before being disposed of, my morning coffee and the 4 docking stations in boxes that haven't got a home yet.
I REALLY miss my old 17" laptop. My next home one won't be from Apple - they've gone so far off the rails they are out of contention now (non-upgradable memory, non-upgradable storage, fsck that !).
But at work that standard is 13" laptops, which by the time they are rescaled to actually be readable are only of use for parking things like the Skype window on - till that goes away shortly :( Clearly the entire IT section is run by youngsters who don't have eyesight problems ... yet/
When I built my new workstation, one of the applications I was trying out for controlling the many ARGB lights inside the chassis used a static window size of 1024 x 1080, which is larger than the monitor I have on my test bench (1280x1024); Made for moving around in the app *quite* annnoying.
(I ultimately ended up controlling the fans using a dedicated microcontroller, because nothing in the PC chassis market was able to do what I wanted it to do.)
Fixed dialog and application window sizes are NOT best practice for ANY platform, period.
God yes.
Same with physical design, if you design a building and propose to use things like doors of X width and weight, if this is the first time you've done this then before building commences get a bunch of elderly and disabled and see if they can actually use it by mocking up a door and corridor somewhere*.
I'm shocked at how poorly designed many new buildings are for disabled as an example they meet the legal minimum for access but that's it, and new build housing is even worse (you might be able to get a wheelchair down a hall, but turning it to get into a room off to the side is another matter).
I was in a retailer the other day that had a "disabled lift", which is great, not so great was the fact the door was extremely heavy to open (I struggled with it, my dad was in the wheelchair and we needed a member of staff to hold it whilst I pushed him in),and the actual lift was barely big enough for the wheelchair to go in - you could not easily have opened the door from the wheelchair, you could not turn the wheelchair around in the lift, and if you were being pushed, your assistant could not fit in the lift with you, and the internal control for the lift was a little black lever. that was pretty much behind the wheelchair on one side and hard to see in the dim glow from the low output bulb in the ceiling.
I think the lift was about 75cm wide and maybe 90cm deed, literally the "footprint" of a wheelchair.
The similar disabled lift at my GP's (both are the sort that are retrofitted into a small space), actually has lightweight doors that are mildly assisted in opening, large button controls that light up on both sides of the lift once in, and actually has room for a career to get in at the same time.
One was I suspect designed for a small stock trolley (push it in, walk up the stairs and call it) and redesignated so the store met the legal requirement for access, the other was designed with an actual disabled person in a wheelchair in mind.
So much UI both in tech and the physical world is designed and built by people who have no clue about what the users actually need, or can use.
Sorry minor rant there, but whilst I'm not disabled, I've spent 40 years seeing how utterly useless many corporate attempts at "disability access are", and how rather than things getting better in many cases, especially tech they're getting worse. Simple things like remote controls getting smaller with fewer buttons and a reliance on screen displays or voice make it actively harder for those with poor manual dexterity, eyesight or hearing - pretty much everyone over a certain age ;)
*An example of this was back in the late 90's several of my local stores were actively trying to make it easier for disabled people and had staff asking customers, the result was during refits several stores fitted automatic doors or added assisted opening devices to the existing ones, and the local bank converted a side door to a ramp access for disabled and buggies (the main doors were huge, heavy and up several steep steps).
"you might be able to get a wheelchair down a hall, but turning it to get into a room off to the side is another matter"
That reminds me of the North Sea oil production platform I visited where, when I got them to run an emergency drill with a stretcher casualty, they found they couldn't manoeuvre the stretcher into the hospital bay - the corridors were too narrow to turn it. They ended up building an external access door from the external walkway, plus an extended platform for manoeuvring. One of many cases I found during my career where the designers had never been users and lacked the practical application experience.
I did a day skipper course for how to manage a yacht. One exercise is "man overboard" which is a bucket, a float, and stick with a flag on the top. You learn how to turn the boat round, and get back to the MOB and pick it up. We all passed.
At lunch, we were anchored, having a nice lunch, I asked if we were to be taught how to get someone out of the water. No -- that's not in the syllabus.
So being in the med, in the middle of summer, I jumped over board saying "Man over board".
Every one burst into action
They threw me a rope. my hands were so cold I could not grip it.
Someone tied a few knots in a rope and threw it - again I could not grip it
Someone tied loop in the rope and threw it to me. Great - I put it under my shoulders and they tried heaving me out - they could not.
25 minutes later someone had the idea of using the mainsail winch - and I got out.
In real life I would have died.
If you have procedures you have to test them!
I was at a customer and some emergency stuff (key to the power room?) was locked in the key press. During practice it all worked fine. When they had a real emergency, the shift manager with the key was in a meeting with the senior managers. The senior managers were surprised when three guys burst in unannounced saying "we need the key - NOW" - and every one ( including the senior managers) rushed back to the ops room to help restart the systems.
Another customer had a wonderful document about what to do in an emergency - it was well tested, and online. After a power outage, they could not access this document because the server it was on was not active. Fortunately some one had a old paper copy which said ... start these server first... then you can access the document!
"Another customer had a wonderful document about what to do in an emergency - it was well tested, and online."
I recall an offshore installation where the operator's management were insistent that their online document control system was adequate and paper documents could only be printed off for individual work permits. Even when I pointed out several situations where staff needed paper copies for reference during routine tasks, my concerns were dismissed - in fact, the company approach was to remove the paper copies so staff had to work from memory. Definitely unsafe but, at that time, I didn't have enough authority to shut them down. However...
Later in my visit I discovered their power restart procedure* was held on a PC in the main control room. Unfortunately, the PC was powered off the standard ring main for the room (one that also powered a kettle, etc). Only critical safety equipment was supplied by the backup inverters (itself supplied by a bank of 12V lead-acid batteries) - a ring main was not classed as safety-critical (especially if it also supplied non-critical high-drain items). When I raised this with the installation manager (OIM) he proudly produced a paper copy from the desk drawer - I couldn't catch him out with that - at least, not until I took it from him and started to tear it up!! Their document control system was updated to allow (and control) paper copies by the time I next flew out there.
*There are a number of situations where plant will automatically shut down for safety - all designed to fail-safe with procedures to ensure a safe restart. One bit of plant that can shut down is the electrical generation module (often gas turbines running off produced gas, or with fuel shipped out from shore).
Fully agree Noram, it reminds me of the 'care' home where my father in law ended his days on earth. With very limited mobility he was assigned an upstairs room at the end of a long corridor, where unsurprisingly encouragement to eat in the dining area with other guests was politely rejected. Why? He could about manage to make it to the landing but was then faced with three flights of stairs with 90 degree turns to negotiate with his walker frame, or struggle a bit further to the lift. The lift was very much a goods lift available for people if required, but needed a very hefty shove to open it and the safety interlocks didn’t activate without a similar hardy shove from the inside, something that this frail 86 year old simply couldn’t manage. If he was put in the lift like a sack of spuds and met at the bottom there was every chance that he’d fall during the descent. In his wheelchair he had no chance of reaching the button once the door had been slammed shut from the outside so his only means of getting out was for someone to squeeze in there with him. The poor chap had long since given up; it was almost a relief when staff found him ‘unresponsive' one morning. Sweet relief had eventually arrived.
I have a friend who's been wheelchair-bound for a few years to who I frequently transport. One public building we visit has a long sig-zag ramp to bypass its main steps but a tiny lift. Worse than being tiny its upper floor doors are at right angles to the ground floor door so the wheelchair has to be turned round inside the lift or she wouldn't be able to get out. Fortunately her new powered chair can more or less spin on its own axis.
We've just got back from a short break, and it's been something of an eye opener for me. SWMBO has health problems which means walking is slow and painful, so we took the wheelchair - lets just say, I normally put on weight through making good use fo the help yourself buffet breakfast, this time I didn't.
Both hotels were accessible - in principle. We even had specific accessible rooms (wet room showers, that sort of thing.
The fun when you have to present the RFID keycard to open the door, shove or pull it open against a heavy closer, and get SWMBO pushed far enough to hold it open while we get through ... is "interesting." I really don't know how someone self propelling a manual wheelchair could do it.
The upside is that we found people surprisingly helpful - apart from the Passenger Assist people who failed to turn up at our local train station as booked, meaning that SWMBO had to struggle down and up the steps to use the subway.
As the primary carer for a wheelchair bound SWMBO I can assure you that your experience is the norm. Most facilities that are 'accessible' seem to have been built from designs generated by LLMs that have ingested the mandatory requirements but have no insight into actual real world situations.
We (partner & myself) look after a mobility impaired elative, sometimes she will be using a frame, sometimes walking small distances, other times in wheelchair depending how he is that day / time of day.
So, iin areas of house she uses stairlifts, wet room with access for wheelchair, wide doors, grab handles etc.
Getting house disabled friendly took a while when we first moved in.
Lack of good disability access is a pain.
When we take her out for meals, we generally end up making bookings at a relatively small number of places, as we know it is possible to navigate the chair around them, no steps etc. *
* Partner & I both getting on and so long since past the age when we could lift relative in chair up some steps without it actually causing us physical issues! So, if we look at a new restaurant / pub for meals we do a recce first as lots of supposedly accessible places are not (far too may initially look OK but fail at last hurdle of the toilets not really being properly disabled friendly)
> actually has room for a career to get in at the same time.
That is good.
Too many of these lifts assume that, once you are too infirm to do without them, your career has shrivelled up and therefore they can take their own sweet time getting you up one floor, let alone two, as you clearly have no need to be anywhere else than right there, trying to figure out how to reach the controls.
Well as an 85 yr old now I am in the 'cannot always see what the stupid thing means' category - so buttons, labels, are often too small, labels not obvious etc & we can't always be with a translator. I can do anything on my desktop because I can make things the size I need - trying to run my world on a phone became ridiculous - so I am back on a flip phone ( 'smart' phone now in the drawer) - do not use it for anything but calls & texts, and think the world is now really stupid as people walk around with a phone plastered to their faces ! I do not much like 2025 ! Grrr !
We were reveiwing a new 4 story building and I was tasked with assessing the emergency processes. 1) The only way you could fit a stretcher in a lift was at an angle of 45deg from top left to bottom right. (try it in your own lifts!) 2. The stairs were also very narrow with small platforms adjacent to each floor, you could lower a stretcher vertical down the center of the stairwell!
We had to provide wheeled carry-chairs on each of the upper floors as that was the only way of getting an ill person down to the ground floor.
me: "Grey text on a grey background is not easy to read in a well lit area " ....
All testing should include it being used by someone ancient, like me, who no longer has 20 year old eyes.
Oh, THIS! I was a poll worker at US elections when the new online voter registries were rolled out (some years ago). The average age of the poll workers was probably about eighty, and the screens to enter name and check registration were: HUGE LOTS OF WHITE SPACE WITH (tiny little letters in the center) - I don't know how to change font in a message, you get the idea.
I called for a support techie - he might have been old enough to drive - and told him to watch the old dears try to read the screen. One kept lurching out of her chair to squint at the screen four inches from her face, another kept picking up the laptop each time to do the same. A third had a Sherlock Holmes sized magnifying glass. I said, is there some reason the text has to be minuscule, and is there any way to fix it now?
Well, it was fixed, but not before the next election. That was a LOOOOONG Election Day.....
I know a guy who works as a tester, and is quite proud that he can break things, and find flaws where others cannot. Isn't that, erm, part of your job?
Speaking of breaking things, much of my working life has gone as follows:
Me: "Hey boss, come and look at this cool thing I've wrote, which I've tested and works perfectly"
Boss: (looks at software)
Software: (boom)
Ah, the cybertruck windows were down to a complete failure to understand that "bulletproof" glass absorbs the energy of the bullet by a combination of glass fracturing and a separate polymer layer deforming permanently. Alas, KITT's bullet proof windows must remain forever out of our reach.
> I know a guy who works as a tester, and is quite proud that he can break things, and find flaws where others cannot. Isn't that, erm, part of your job?
Sure, that's the job, but nothing wrong with taking pride in being good at it!
As a programmer, a tester who can find all those edge cases (and communicate them clearly) is very useful
I have kids for that.
10..12 year olds can read and are inquisitive enough to find all the things you never even thought about in software.
5..6 year olds are mobile destructive forces you can use for hardware testing. If your kit survives that it's above milspec.
:)
I have kids for that.
10..12 year olds can read and are inquisitive enough to find all the things you never even thought about in software.
5..6 year olds are mobile destructive forces you can use for hardware testing. If your kit survives that it's above milspec.
The only problem is they keep aging out of the range for optimum testing, and you have to keep producing them to ensure you have some ready at the right age to continue, at least until the eldest contingent starts producing a second generation of testers....
My first real job in IT was in testing. My leaving speech was "This is one of the hardest jobs in the company". [Cue groans]. "Because you [pointing at product-speccing people] spend a lot of time designing something, then you [pointing at coders] spend even more time making it all work and you [pointing at graphics people] make it look great for the customers. Then we [testers] come along and say [puts on whiny voice] "You missed this. That bit is broken. This function doesn't do what it's meant to"."
It's a worthwhile job but it doesn't make you any friends professionally!
I learned a long time ago. Spend a few days or weeks with the people who do the job before you even think about the design. Keep them involved every step of the way. The difference between functional and WORKS!
It's a worthwhile job but it doesn't make you any friends professionally!
I’m a coder, just for the record a good tester is something I value highly.
A good tester will find all the right bugs, not get hung up on the unimportant ones and will give good bug reports with easy to follow reproducible steps. (Often something simple like remembering to include the id of the record in a screenshot; or just putting what account you used).
They are to be valued.
At <insurance company whose system I originally built/>, if I or sensible management had a reason we didn't want a release to go out in its current state, but others were being pushy, we just added me to the testing team for an hour or two. Didn't even have to dig up bodies that I'd buried myself most of the time.
Yes, but as a tester, how many times have I been told "Stop Testing, you're finding too many defects. We've got to make the release". OR "Change these defects to enhancement requests or you're fired. We have to make the release date". And yeah, I'm in an industry where you don't want to see defects. But as long as the primary measurement is "Cost Reduction" and "Time To Market", nothing will change.
Decent feedback. Problem is culture. At NHS I complained about the new "background" management had decided on "Its unusable. White background means all the icons blend in". Shutup and get on with your work, is essentially what they said. I told ALL the users that were moaning at me about it to raise a complaint as I'm not listened to. They did, the background got changed a week or so later. I got no thanks for originally bringing it up.
Then another place a user was testing new software so we went to ask her how she was getting on. She pointed out issues and flaws. I said fine we'll go away and work on them. While walking back, the tit of a manager I was with said "She was really negative." I said "That's how testing works. They test it, point out the flaws or issues as THEY are the ones that will be using it. Its normal, its not personal".
The fuck whit.
I was always good at breaking things too. It started at school with fellow students writing BASIC programs. "Enter a number from 1 to 5" was just inviting me to enter anything but, and they learned an awful lot about the importance of input validation from my actions.
The outstanding one was crashing the stuff written in Ada in my first proper job. It was trumpeted as being wonderful and rigorously tested etc. I was doing some testing on some aspect of the system and as part of it I had to navigate a page full of input parameters, which I filled in by alternating "0" and the enter key. I should note that this was on a VT220 terminal, to give some idea of the state of the UI. Having done this successfully numerous times, suddenly I got the thing to crash. The fully-validated input module took whatever input I'd given it and barfed. I mentally went through the muscle memory of what I'd just done and realised that I'd missed the 0 and hit the minus key next to it. This was an input it would accept because the number fields were for signed decimal numbers, but it turns out that having gotten past the initial input filter that took out all the characters that were not part of a number, what followed couldn't cope with a single minus sign as the entry because there was no numeric digit in the string. On a roll, I tried it with a + sign too, and got the same crash result. What a deeply satisfying day that was, breaking something that had passed all the required verification testing. And no, it's not one that had occurred to me before that day either, but you can be sure I've tried it on stuff ever since.
> "them: 'It is meant to be obvious...'"
My Calculus I teacher told a story from his undergrad days. He was attending a mathematics lecture, and his professor was working through a complex proof on the blackboard. At one step, the prof explained "it's obvious that..." he paused, repeated "It's obvious...", and stared at the board for a moment.
He spent the next 20 minutes quietly filling sheet after sheet of notebook paper with equations before looking back up at the board and stating (with full confidence this time) "it's obvious that... (whatever the next step in the proof was)".
I had the opposite problem with Santander online banking on my 4K desktop. After a website update I couldn't view my statements. They appeared as onscreen PDFs in a narrow vertical div centered on screen. It was impossible to read or access the print or save buttons as they were invisible outside of the narrow div and the horizontal scroll was limited. Tried different browser, same. Naturally they had also removed any simple ways of reporting such problems. I found by accident that the problem disapeared if the browser window was not maximised but set to around half the screen width.
My credit union created a problem when they changed how to access online monthly statements, which were PDFs. They apparently had a separate server run by a different company that was hosting the documents and it was supposed to pass the credentials and open another window. The first time I tried to access my statement after they did this, I got a new tab in the browser but nothing in it. I tried logging out and back in, clearing the cookies. Made sure that site was allowed popups. Nothing worked. Then I tried another browser and it worked. It turned out whoever had designed it had only made it work for Safari on the Mac and Internet Explorer on Windows and no other browser worked. After a few months, they got it working for Chrome and much later for Firefox. Then years later, I was changing my ISP and so was changing email address for everything since I'd used the one supplied by the ISP I was leaving for everything important. A few places I just couldn't get them to accept the new email. The credit union was one; I'd changed the email address in the settings, but it kept sending the monthly emails that new statements were available to the old one. I even went in and tried to get them to fix it and they couldn't figure it out. I eventually accidentally figured it out when getting statements and saw something on that page that seemed to indicate you could email if there were issues. Apparently, when the credit union first set things up with this other company, they gave them account holders emails and that company kept them separately in a profile that could only be changed while accessing the statements or other online forms because there wasn't an independent login.
Indeed. My brother, then probably 2yo, showed our mother how to open a Children's Aspirin bottle -- with your teeth.
One enterprising child I saw took the "push down and turn" childproof cap to a carpeted floor, put the bottle cap side down on the rug and leaned on the bottle while turning......
I happen to like to write documentation. Beware: this is a very frustrating or very rewarding activity. You've been warned :)
So many times, even today, I have the following situations:
- be in a meeting with someone I've sent the doc to (that never fed back on it) that asks a question, showing blatantly he's read 0 page of the doc, to which I reply "yes, it is in the documentation", to which he embarrassingly replies "ah yes, yes ..." in a tone that leaves 0 doubt to anyone in the audience
- be in a meeting with someone I've sent the doc to (that never fed back on it) that asks a question, showing blatantly he's read 0 page of the doc, to which someone else, who was not in the dist. list and didn't have an immediate need/role in reading this, in the meeting, interjects "it is in the documentation !). This is priceless, rare but priceless.
If you're talking about the saying: "the definition of insanity is doing the same thing again and again and expecting a different outcome", that's fucking terrible definition of insanity.
Not least, because most of the time it's applied to someone doing the same thing but with different starting conditions.
I agree that it's not a good definition of insanity*, but I do think we need a word for whatever that is, because I get frustrated by that far too often. People who, because they don't know what to do, try the same thing over and over even though they have no reason to believe that anything has or even could have changed so it will work where it didn't before.
If it said "try again later", fine, keep repeating it. If you've changed something else that should unblock it, okay, run it once more. If it's exactly the same, pressing the same button on the theory that it will eventually do what you want instead of that thing that button does is a bad idea, and I wish I hadn't seen people use that approach.
* I also have trouble coming up with an actual definition for insanity. Defining mental illness is hard enough, but defining that unclear line where it goes to that higher level has often proven challenging to me. Usually, I think that the core part has to be dissociation from reality where they either invent nonexistent things or fail to recognize existent ones, but that too can be hard to define. It's a good thing I'm not a psychologist.
Years ago, my folks were selling my childhood home. My father had converted the walk-up attic into fully-usable living and working space - HVAC, drywall, carpet, etc. But didn't get a permit at the time. Years later, when selling the house, he tried to get it permitted, and was told it had to meet a huge list of *current* requirements. One was an arc-fault circuit breaker (I think; if not that, something similar).
So the electrician installs the replacement breaker - which promptly trips. So he goes to the first outlet, pulls it from the wall, unwires it, wires it back up, turns on the breaker - trips. So he goes to the second outlet, ... (repeat for EVERY OUTLET in the space). My father, knowing the wiring has worked fine for well over a decade, stops and thinks. Then he checks the wiring on the 3-way switches for the stairs light. Sure enough, had live and neutral switched (I think; it's been a few years). He quietly moved them to how they were supposed to be. Electrician finishes rewiring the (perfectly fine) outlet he's on, turns on the breaker - hey it works, job done.
The electrician would have gone through every single outlet, not troubleshooting but just unwiring and reconnecting, if my dad hadn't figured it out himself.
* I also have trouble coming up with an actual definition for insanity. Defining mental illness is hard enough, but defining that unclear line where it goes to that higher level has often proven challenging to me. Usually, I think that the core part has to be dissociation from reality where they either invent nonexistent things or fail to recognize existent ones, but that too can be hard to define.
ref. Donald tRump
"Usually, I think that the core part has to be dissociation from reality where they either invent nonexistent things or fail to recognize existent ones, but that too can be hard to define. It's a good thing I'm not a psychologist."
A certain politicians speeches seem to meet the requirements as described. Beautiful speeches devoid of reality and content.
"the definition of insanity is doing the same thing again and again and expecting a different outcome"
Sometimes I do something every day, and it works. Every now and again - it does something different.
And the opposite. Something is broken, so I start to debug it - and now it works.
Timing problems are a curse.
"If you're talking about the saying: "the definition of insanity is doing the same thing again and again and expecting a different outcome", that's fucking terrible definition of insanity."
I believe it was Einstein who said it. I think it would be his comment on quantummechanics in general and the uncertainly principle in particular.
It's often quoted as from him, but it seems to have a somewhat clear spread from non-famous initial usage in the addiction recovery area three decades after Einstein died. Unless those quotes were made up too, it also makes more sense in that context* than it does in modern usage, where there is insanity that doesn't involve mindless repetition and mindless repetition which can better be described as stupidity than insanity.
* The first quote used "insanity" to contrast with "sanity" which was being used as a synonym of sobriety or at least a lack of addiction and related negative effects on life, and the repetition concerned involved the repeated acts of someone with an addiction even though they knew it was harming them. Suddenly, it actually makes sense to me how that quote would have come to be which makes a lot more sense than IT people dealing with frustrating users. Incidentally, although I previously knew that the Einstein source was misattributed, I only read about this initial usage about five minutes ago.
If you're talking about the saying: "the definition of insanity is doing the same thing again and again and expecting a different outcome", that's fucking terrible definition of insanity.
Especially if it's applied in relation to someone whose ever owned and tried to start a petrol lawnmower, chainsaw or other similar piece of kit...
One of the thing I've done over the years is write procedures, primarily for equipment operation. At one place I worked, there was a group of people that were supposed to review the procedures, give feedback on them and approve them. Some people were notorious for letting them sit on their desk for months, so management fixed that with procedure review and approval meetings. The procedures were still sent out for review as before, and after all feedback received was incorporated as appropriate, they would be put on a meeting agenda where everyone needed to sign for approval would attend. That fixed the problem previously mentioned, as at the meeting they would have to either give feedback or indicate they would sign it. However there was this one guy who would send feedback, but hold some back so he could present it at the meeting. He did this every single time he was required to approve a procedure, which guaranteed it would take 2 meetings for any procedure where he was involved.
Premonition of our new AI golden age?
Having read many "fine" manuals, I can understand why many users give up on principle before starting. The idea that introductory documentation should concentrate on leading the new user through the basic and common operations, seems to rarely occur to the documentor.
K&R The C Programming Language 1/e this point was brought home to me in the late 1970s where the now legendary program containing printf( "hello, world\n") appeared on the first page of chapter 1, without a long digression on the intricacies of the printf family or variadic functions in general.
The UNIX seventh edition documentation was very similar, so I imagined was part of the cultural DNA of Bell Labs.
> The idea that introductory documentation should concentrate on leading the new user through the basic and common operations, seems to rarely occur to the documentor.
So much this. Links to the appropriate reference pages can be included, without overwhelming the user with a common use case who just wants a "quick start" guide.
This is similar to technology product advertisement. An ex boss of mine said such advertisements should answer the questions:
1 What is it?
2 What does it do?
3 What is it good for?
Something that appears to be lacking in many of today's adverts, leaving you non the wiser as to what this particular black box does.
Well, of COURSE not. If you found the program and it;s README.TXT or man page, you already know you want it and by definition know what it does. </sarc>
A lot of the issues with OSS, I feel, is the whole "academia" ethos of "do your own research" because often that's where the authors are or have only recently left. The bit they often fail to realise is we ARE doing the research to find the documentation and it's often NOT helpful and then have to rely on others who, with more time, have figured it out and written a more helpful blog/forum post, which may or may not be canon or current when the actual documentation really should be the current canon.
I'm currently trying to sort some WiFi issues on FreeBSD and all kudos to the recent and fantastic movement in that area of h/w support, but I don't understand enough to be able to follow what I need to do. There are multiple threads on forums trying to help people which assume knowledge I don't have and partially cover what's needed. No one, as yet, has written a simple one page How To that says things like "do this, change that setting, do that and it should work, and if it doesn't, try this, that or the other". If I eventually figure it out and no one else has, I'll do it. But it doesn't work for me yet, so I can't. Currently there are mostly only GitHub pages which say things lik e"check your chipset is supported". But tell you how to check what your chipset is and/or link to the list of supported chipsets. (They may do now, but I already gave up and went back to Ethernet. I'll look again in a month or so and see if I can get any further)
I think the problem is more that (except for a few people), writing documentation isn't fun or easy. Plus (over simplifying and applying a lot of generalisation) there's a tendency that people drawn to working in FOSS projects, generally aren't natural candidates for manual/documentation writing. Developing the program/system needs a different skill set to writing documents.
There's that and the fact that what seems obvious to a dev, especially the one who developed that programme may be unknown to the user, or may (often the case) indeed be obvious, but actually you can't just do that because it needs a prior step explained first, or even one before that etc. Commonly telling the user to do X. But not telling the user how to do X, where the doing requires a specific set of steps. Or not telling the use where to find the X menu or omitting to say that before you do X you need to do Y, which you won't be able to do, because that happens to be something that only gets explained 12 pages further on in a totally different context
The most obvious (hardware) example is telling the user that to change the battery they need to remove the cover from the battery case (unsurprisingly) , without saying where to find the battery case, or that the lid needs to be moved anticlockwise to open it.
TMMM starts with differentiating between the professionally produced product and two people working out of "a remodelled garage" if I remember the phrase correctly, the difference being about an order of magnitude. Nowadays, however a lot of FOSS does indeed come into his category of a product. I mentally categorise things into product or project and all too often the home page of the latter used to consist mostly of the release history or a "News" link that pointed to that. Now, of course, even if it has an address for a home page it points directly to Git(hub|lab).
4. What it doesn't do.
Eventually you get used to reading descriptions etc. & taking notice of what's not there. Remember that humongous T&C, EULA, privacy policy or whatever about Windows telemetry? It gave a few examples of what might be taken but there was no statement as to what wouldn't.
The worse subset of bad documentation is where it doesn't tell you how to quit the ****er. Just yesterday I was experimenting with some code, and had absolutely no idea how to get out of it, I ended up killing the (virtual) machine.
Edit: A quick detour to check some of my own documentation, and in the first one I checked THE FOURTH SENTENCE in the readme says how to quit the program. (Could even be the third sentence if I put a semicolon in, but I adhere to "no multiple subordinate clauses" as best as I can.)
My documentation used to start:
"This document is for the $COMPANY Messaging team. If you are attempting this operation and not part of the Messaging team, STOP NOW, and contact your supervisor or the Messaging team. Do not go further."
I felt that that was a) enough warning and b) clear enough to save my arse had someone not on my team fucked things up.
> K&R The C Programming Language 1/e
Marvelous book. Thin, readable, thin, has a complete description of the language, is thin. Only slightly thicker than the LISP 1.5 manual, IIRC.
Straight out of Uni, I had never used C - Pascal, FORTRAN, BASIC, LISP, Prolog, SNOBOL, COBOL, Simula, Forth, Assembler[1] - but no C. The first paying gig was using C and they were going to run their tutorial over the first week, starting Tuesday - but I'd nipped out to Foyles, picked up K&R and had time to read it cover-to-cover a couple of times on the Monday, so Tuesday was diving straight into their codebase. Which was quite readable as all I needed to know about the language had been in that slim volume.
A while later, Lua was almost as well served, one readable book - and that also included all the info needed to merge the interpreter into my app as an integrated scripting language. Three days from "is there a nicer (to me) embeddable language than Tcl?" to "my app is now fully scriptable, here are a set of examples". Ok, did have to know C to understand how to do all that.
In more recent years, the recommended O'Reilly volumes for starting off with Python make up a block of purple on the shelf - and trying to use "just" those still doesn't make me feel confident about diving into existing Python code (as opposed to making some new short bit of MicroPython). Maybe if I also wade through that tome about Idiomatic Python it'll help? Is Ivar strong enough to hold it all?
[1] all of those covered in enough detail within a single, slim, volume to get you started - "User Manual and Report", Griswold, Clocksin & Mellish, one Sybex volume per microprocessor architecture etc. OK, Winston and Horn is way thicker than the LISP 1.5 manual, but it does cover a lot of examples beyond teaching the language.
What infuriates me is the opposite problem -- documentation written *solely* for an audience who is new, not just to the program in question, but to computers in general.
Pages and pages of drivel like this: "To do X, click the X button. To do Y, click the Y button. To do Z..."
Without ever explaining the implications of doing X, Y, or Z, or how this choose among them. If they're similar.
documentation written *solely* for an audience who is new, not just to the program in question, but to computers in general
A variation on this is the manual which starts with how to install it - which might, in fact be how to compile from source and install it.
No, I do not need to know how to install it. I'm sitting in front of it. it was installed as part of the distro, or, in a business environment, as part of the build, or it's on the computer of somebody who asked me to help. I want something that tells me what it does and how to do it. If it needs installation instructions refer me to the Appendix which is where you could have put it. I don't want to lose the will to live thumbing through instructions to do something that's already been done.
It is all fine for *you* if you have the luck to have the software already installed. But not everyone will be in that position.
And does the author of the documentation have any idea at all that you are in that happy state? Heck, do they even know that anybody has decided their software is interesting enough to be included in a distro or prepared build? From their p.o.v. installing is step one.
> I don't want to lose the will to live thumbing through instructions to do something that's already been done
Literally thumbing through? So a dead-tree copy? In which case, the index told you that chapter one was all about installation and you want to jump to page 17. If it is an online manual or PDF then chapter 2 is one click away from the index - well, maybe the index in a badly-formatted PDF isn't hyperlinked, but typing in the page number is easy enough isn't it?
Ok, if the docs are just a long HTML screed then hitting page down gets to be a pain - but then that is also usually a sign of a one-man-band (or just-a-pile-of-devs for a larger, almost certainly OSS project) and, as we all know just how (cough) good devs are at writing documentation (there are good reasons that tech writing is a distinct job), we're just glad to have documentation!
> it was installed as part of the distro, or, in a business environment, as part of the build,
Sticking with digital instructions, one of the indicators of a *good* pre-prepared install is that they also trim out the bits of documentation that are no longer relevant. Like integrating with the other packages (chapters 2 through 5 cover the major packages this utility can work with...).
"Manual? Luxury. These days any actual documentation is buried 10 pages down in a SharePoint search and is five years out of date."
Even worse is pop-up tool tips on an application that can't be switched off when they get in the way more than help. It took me 1 project to learn all of the basics of an app and now I have to keep batting the damn popups out of the way which slows me down. I use the keyboard shortcuts as much as possible and keep the mouse pointer off to one side.
Or the "documentation" is a set of discussions on forums across numerous different sites where most of it talks about an ancient version that has no relevance to whatever is available today.
Case in point, my Linux setup wasn't making any sounds. So I followed instructions I found but it failed. Posted for help and the response was "oh we don't use that sound system any more" (I don't remember if it was alsa or pulse, but it was one and it's now the other, or something).
I literally just installed this OS, how the hell am I supposed to know this? Jeez...
[I used apt to reinstall the sound stuff to undo what may or may not have been done before, and when I rebooted the sound started to work <shrug>]
I had to upgrade the IOS on an ancient Cisco Nexus switch. I hadn't done a Nexus before so found the documentation on Cisco:s site...
5. Run a compatibility check
I did and got the same results as the worked example
6. Perform the upgrade
Erm... What's the command? The rest of that step was missing!
I located a possible answer under 'downgrading' and typed in what I thought was the appropriate version and ran it. It just repeated the compatibility check and exited. A reboot confirmed it was still running the original version.
After a few unsuccessful tweaks to the command, I noticed the compatibility check included the the word 'incompatible' - exactly as the example in the documentation! Checking the filename I noticed it was actually for a different switch. Using the correct file it came up as 'compatible' and installed.
Tried giving feedback to Cisco but they were not in the least interested as was on their EOL list and not the latest shiny-shiny
"Tried giving feedback to Cisco but they were not in the least interested as was on their EOL list and not the latest shiny-shiny"
I see this and wonder why companies don't update older incorrect documentation and add later notes as issues come up. Yes, that product is long gone, but plenty of people might still use it and if they've had a really shitty experience with your company's product, they may not look favorably on the brand in future. Lost sale. I bought a lab power supply second hand from somebody local and needed a service manual for it. B&K Precision didn't have it on their website, but a service tech dug it out for me, and sent me a .pdf in under 24 hours. It's now on their website too. It was one of the best support interactions I've had in ages. Due to that, I browse their products when I'm looking for electronic test gear to see if they offer what I need.
"These days any actual documentation is buried 10 pages down in a SharePoint search and is five years out of date."
I'm still learning how key elements of the android apps I'm using to monitor my health problems actually work. 'Searching' never actually gets me anywhere, and the latest 'upgrade' to just crashes when you try and search at all!
And why can't different functions in an app use the same steps to achieve the same thing. PERHAPS writing a guide to standardise HOW things work could be a better starting point ... even before a manual?
And why can't different functions in an app use the same steps to achieve the same thing.
Remember the halcyon days of the common windows dialogue standard? File->New,Open,Close,others,Exit; Edit; View; other things; Help. Ah, but no, that would constrain our creatives' creativity! Can't insist on everybody having the accelerator pedal on the right, I want it to be a yellow pull-and-twist button on the dashboard!
> F9 for Refresh - originated in Notes, quickly adopted by Outlook, but no other MS products (eg, recalculating tables in Word).
F9 is spreadsheet recalculation in Excel. Of course by default spreadsheets recalculate automatically, but it's handy if you have a big complex one that you know you'll be making a number of changes to before the final results should be (re)calculated.
Err, handbrake surely? Or are we thinking of different models?Had a nifty little release trigger inside the "spade handle". If you were in the left hand seat, the trigger was conveniently placed for the forefinger of your right hand.
If you were driving the UK model the trigger was under the pinkie finger of your left hand, unless you twisted your hand through 180 which felt awkward.
If it was parked for more than about ten minutes, you couldn't put a Denver Boot on it!
> everybody having the accelerator pedal on the right, I want it to be a yellow pull-and-twist button on the dashboard!
On my tractor it was a steering column lever like a turn-signal but on the other side. Farm tractors may run constant speed for hours.
(Actually this was the deluxe Road model and also had a foot-pedal.)
Letting up on the accelerator pedal has always caused the car to slow down, so it actually makes perfect sense.
At least in Europe, where the regulations require deceleration over a certain threshold to illuminate the brake lights.
But not in the US, where it's only the brake pedal...
My concern is the change of emphasis, from (a) "the primary way of slowing/stopping the vehicle is with the brake pedal, but yeah, if you're only slowing a bit you can just ease up on the gas" to (b) "you're only supposed to use this one pedal, but the brakes are there for emergencies".
If you've spent your entire driving life under (b), you won't have the brake-pedal muscle memory in an emergency, when fractions of a second count.
That might not be limited to new generations of drivers, either. My first several cars had manual transmissions, so the clutch-and-shift dance was second nature. But after 25 years of driving only automatics, well, I don't suppose I'd be right back at square one, but I imagine my shifting dexterity would be pretty rusty. That would be annoying (and hard on a car's clutch) until I got my chops back -- but for braking, it'd be a recipe for disaster.
About 30 years ago I was off the road for over a year (tried to snowboard aged 42, broke my neck) and when I restarted driving I decided to teach myself to left-foot brake as I felt like I needed a challenge. It was too, left leg is programmed to stamp down hard on the clutch, then release it slowly, so braking wasn't exactly gentle to start with. Took about 18 months for the "intelligence" to move from brain to spinal cord to left leg but after that the reflex was fully programmed in and I'm pretty sure that the half-second gained by not having to come off the accelerator onto the brakes once saved me from a serious coming together with an errant white van man who came straight out of a side turning.
The technique is pretty fail-safe as if I ever get confused I end up with both feet on the brake which is no problem. I still occasionally drive manuals and have no problem adjusting to using a clutch when I do - spent time last week hammering around Brands Hatch circuit in a Dodge Hellcat and a 1966 race-prepped Ford Mustang (bloody great iron V8 up front, race tyres, no power steering, insanely heavy clutch) as a birthday treat. Now that I have to renew my licence every three years it seemed like a good idea to get my driving independently assessed :-)
We can thank Steve Jobs for that.[1]
He's the one who insisted on that consistency in Mac applications. To get it, Apple had (perhaps still has?) a very detailed UI style guide that app developers were more or less required[2] to adhere to.
Then, as it has so often done, micros$t cribbed from someone else's work to create an imitation just good enough to fool the naïve.
[1] I'm not an Apple fanboi -- I've never owned one of their devices, and I'm aware of some of Jobs's less appealing character traits. But this was a case where his rather dictatorial mindset proved to be a benefit.
[2] Hedging because I forget the details of how this was (is?) enforced
... detailed UI style guide that app developers were more or less required[2] to adhere to.
...
[2] Hedging because I forget the details of how this was (is?) enforced
IIRC it was volume 3 of "Inside Macintosh",with volumes 1 & 2 being how to actually write code and use the built in APIs.
It wasn't enforced, and couldn't be. Naturally, certain established developers - including Microsoft IIRC - tried to just port from other platforms and do the bare minimum to make it work. That resulted in programs that were modal* and had very non-standard (from the Mac UI PoV) interfaces. Except for very niche programs, the result was "user dissatisfaction" that essentially forced developers to sort things out or see their program die because a different program that people liked using ate their sales.
And that's one (of many) things that really pees me off as I have to use Windows for $dayjob. The way different programs from the same manufacturer (yes, Microshit again) have subtle or major differences in UI. it can be little things like most programs scrolling whatever window is under the mouse pointer - but Excel only scrolls if it's the active window, and it always scrolls if it's the active window. Add in that Excel hides the cell highlighting when not the active window (because you had to switch windows to scroll a different one), and it gets even more annoying. And then you get things like Outlook using totally different keyboard shortcuts to every other MS program - meaning that (since I use a Mac at home, and so have to be coping with two different UIs anyway) use keyboard shortcuts far less than I could simply because it means spending so much time thinking about what the hell I'm currently working on and so what the right shortcut is.
* In 1984 when the Mac came out, most software was modal - i.e. you worked in one mode for one thing, had to exit and enter a different mode to do something else. You could only do what was in the limited menu available in the mode you were working in. Take something simple like editing text. A typical word processor of the day had an edit mode - you opened a document and could edit it, but couldn't print it. To print, you had to save it, exit back to the main menu, and enter a print mode from where you could print a document (which you might have to select and open as it might not be remembered that you'd just been editing it.) The you'd exit the print mode and re-open the document in edit mode, and ...
The Mac introduced modeless operations - you could be typing away in your document and at any time just select Print from the File menu (or hit Cmd-P). For most developers at the time, the idea that the software had to handle user commands whenever the user wanted to use them, rather than when you permitted them, was a major change in thinking - leading to the Mac having a reputation for being hard to program.
"[Apple's style guide] wasn't enforced, and couldn't be."
"Enforced" was perhaps a poor choice of words on my part; but it was, as I recall, stronger than a mere recommendation.
Now that I think of it, perhaps it was along the lines of, "if you want any marketing support from us for your product, it had bloody well better adhere to our style guide."
That would explain why it was the likes of m$ who felt free to ignore the rules; I imagine they'd have looked down their noses at Apple's marketing support in any case.
......Can't insist on everybody having the accelerator pedal on the right....
My vintage car has the accelerator in the middle, with the brake pedal on the right. It used to be very common back then. Ford's Model A had the accelerator on the right in the US, but the right-hand drive ones built at Trafford Park had it in the middle.
"Remember the halcyon days of the common windows dialogue standard? File->New,Open,Close,others,Exit; Edit; View; other things; Help. Ah, but no, that would constrain our creatives' creativity! Can't insist on everybody having the accelerator pedal on the right, I want it to be a yellow pull-and-twist button on the dashboard!"
A consistent and enforced interface was what put Macintosh on the favorites list of many consumers. Leaving a program was always "Quit". It wasn't "close" or "exit" or "bye". The keyboard commands were also part of the requirements for application developers for common operations (Open, Quit, Copy, Paste, Print, etc). Sadly, much of that, even with Apple's own applications isn't true anymore. The ubiquitous TextEdit changed "Save As" (CMD-Shift-S) to "Duplicate" and there's some other useless renaming of things. I don't see any value in "fixing" things after years of doing it a certain way using certain terminology. There's also subtle changes to how some operations are handled that fell less intuitive and also a break from how it was done in the past.
Here's a slightly heretical viewpoint. If you're writing custom software for some aspect of a business's operations there shouldn't be a separate application manual. There should be a business manual for taking a sales order, terminating a tenancy or whatever. It should detail the steps taken to do that, manual, conversations with customer or whatever as well as entering the data. That is the responsibility of the department concerned but you can guarantee that if you provide a free standing application manual the department will seize on it. Offer to help them write the fill manual. Preferably starting before you write any code for what I hope will be obvious reasons.
I was faced with a very difficult user. He would break things and complain. We would explain how it worked. He would nod wisely, go away, do exactly what we had told not to do and complain. He was senior enough that we had to do something. So the team collectively wrote a large piece of documentation. We had it poof read by other users, then printed, bound, and I proudly too kit over to him.
He immediately took it, droooed it in the bin, and said "I am not reading any documentation, just make it work for me".
I had to use a BOFH approved user readjustment tool
"He immediately took it, droooed it in the bin, and said "I am not reading any documentation, just make it work for me".
I had to use a BOFH approved user readjustment tool"
Since management rejected the documentation as unwanted, you should have sold it to a book publisher.
I wrote an application for a bank that was notorious for losing documentation. They also had high turnaround. When I left, I not only handed the source code and the documentation in troff format (it was a Unix shop), I also printed off five copies and gave it to them.
Naturally, three months later, I got a call from the new manager claiming my app didn't work, no one knew how to use it, and since there was no documentation, they were going to sue me into the ground, etc., etc.
Although my contract had included on-site support for the followup period, it also had a stipulation that bank caused errors were chargeable at three times my development rate. I'd anticipated this. So they had to approve my coming in, because it was chargeable hours, including commute time, before I'd even look at it.
They agreed, and I was greeted by no less than four bank types who were there to follow me around and document every single thing I did, as well as clock how much time I spent, so they wouldn't be overcharged.
I sat down at the system (System B) and they all watched me do the magic:
$ ./System_B_App
System B Application (C) Copyright Bank of BlahBlah 1998.
For use by Bank of BlahBlah only.
Usage: System_B_App inputfile.csv outputfile.xyz
error: input file not specified. Type "System_B_App -h" for help
$ ./System_B_App -h
This application takes the $DATA CSV formatted output file generated on System A, imports it into System B, and generates an output file usable by the $APP application. If no output file name is specified, the root name of the specified input file will be used.
Usage:
System_B_App -d: show date data - collection date, ratification date, etc.
System_B_App -h: this help
System_B_App -m: generate user manual
System_B_App -t: generate user manual in troff format
System_B_App -v: verify checksum of the CSV file
<cracks knuckles>
"The printer over there is lpt58, right?"
$ ./System_B_App -t | prn lpt58
I walked over to the printer, took the seven page user manual (there wasn't much to it, just explaining the file format fields), and handed the manager the output. I asked him if he wanted more copies, or if he could photocopy them himself, and left.
Of course, they didn't want to pay, but even their legal team had to admit that "we didn't know how to generate the documention because we never even bothered to look at the screen output telling us how to" fell under the "bank caused" error stipulation, and I was paid quite a bit of money for showing them how to type "-h" for help.
End Users are one thing but bright young contractor devs are another...
"Why doesn't the command-line build system do X?"
"It does; it even says so in the help"
"What help?"
"When you go 'mybuild help'"
"Oh, well, you never told us there was a help option! We've only used 'mybuild clean' and 'mybuild'[1] on its own"
Since then, the very first thing it does is print out the "for help, type..." line, even when you'd expect no output at all 'cos the build is all up to date; shudder.
[1] i.e. standard default is to just run the build, the same as Make etc,
"Naturally, three months later, I got a call from the new manager claiming my app didn't work, no one knew how to use it, and since there was no documentation, they were going to sue me into the ground, etc., etc."
Activate Dick-mode. I have an ex-client that made threats. He still tries to call me which make me wonder how I can get numbers I block on my phone to connect those people to a Nigerian pay-by-the-second dirty talk service. This guy called me up for a job and gave me the details (address, access codes, what services he wanted) and seemed very distracted like he was trying to do what humans aren't capable of, multi-tasking, and ended by telling me he'd call me again later. He didn't call me back later which is typical. I did the job the next morning and stopped by another job to do so additional work for him since I was in the area and it wasn't urgent enough for a dedicated call-out by itself. I was trying to call him as there were anomalies at the full job and I wanted to double check that he knew about them. Didn't call me back until the next day and left a message that the job wasn't actually ready for me. Once I'm given an address, access codes and a brief, that's a go-code to do the job as soon as I have room in my schedule unless we work out a later date. This guy wanted the job redone, would find somebody else, wanted a discount, blah blah. Since he was already more work to support which made jobs for him less profitable, I let him know that he should find somebody else. I suppose that there isn't anybody else that he can find at a reasonable price to do a lot of his jobs. I happen to be close enough to the out of the way town he needs service in where others would have to charge a higher travel fee.
If he hadn't tried to make it my fault that he's completely disorganized and I should eat the costs due to that, I might have been able to work something out with him. To get a message where somebody aggressively tells me if I can't come out and redo the job or they'll find somebody else rubs me the wrong way. Odd that, but there you go.
I got dragged from the West Country into London for a "feature" once. I was part of the dev team and it was escalated from the front-line support because they couldn't figure out the problem. So I turned up with one of the support guys who did the interface with the actual people and we went through a bunch of stuff and couldn't find anything wrong. We were literally on the way out the door having given up, when someone made a comment that provided the one piece of information that was missing. I remember we both knew exactly what was happening at that point and pivoted in unison to head for the control PC. It was doing exactly what it was supposed to, according to how it had been designed and configured, but they clearly needed a slightly different configuration.
That's the modern mindset unfortunately. People have been taught "computers" at school, so they should be able to just sit in front of a computer and drive whatever software happens to be on it. I get that all the time with the equipment I install. I replace an EPOS running H######, and get asked "how do I select Product A with subclass B?" HTF do I know, I JUST DELIVER THE ****ERS. I re-install E#### or S#####. "How do I replace a patient's prescription record with out-of-area treatments?" I DON'T KNOW!!!! *YOU'RE* THE *****ING CLINCIAL ADMIN SECRETARY, I'M JUST THE DELIVERY MONKEY!
Late Boomers to Gen X were taught "typing", and created most of the foundations and did a lot of the UI/UX research.
Millenials were "taught computing", by which the schools meant "using Microsoft Word".
Gen Z were assumed to already know, so were taught nothing whatsoever.
Gen Alpha are sometimes being taught online safety. Their millennial parents are helping with that by making Facebook uncool.
In my case it was because my handwriting was so godawful. (Still is). My folks insisted I take typing classes, even though that was deeply uncool for a guy, back in the 70s.
None of us could have imagined how transferable that skill would be to the career I ended up in.
We've abandoned a lot of the UI/UX lessons learned through experience, and ironically it was Apple who both did a huge amount of impressive work (building on IBM's internal work I believe) on strictly codifying their UI elements in order to ensure a consistently usable system across applications, and then with iOS, totally destroying any sense of consistency in interaction and hiding every aspect of the real system from the user. I run an old iBook with MacOS 9 for legacy software and tinkering and the only things that don't adhere to the Apple UI guidelines are video games which were virtually always originally for Windows/DOS. I have an iPad in the loo and I can perform the exact same swipe motion on it 5 times and get 5 completely different results for no discernible reason.
Kids that are growing up on iPad and other touch-screen devices are being taught that tech devices are magic boxes that act in ways that you can never understand because they don't respond consistently and they hide every aspect of the underlying system. Honestly, it's primed them for the advent of AI as well, where they simply trust what the magic box tells them is true and are flummoxed when told that the magic box is wrong, unreliable, and they've failed because they just expect systems to work without understanding how.
I spent 10 years working for a very large, now defunct, chemical company, seven of those years in the engineering department. The company had its' own suite of software, which was state of the art in those days. Much of it had been ported from Vax to PC with a new Windows interface.
I was probably one of the heaviest users (if not the heaviest) of this software, partly as a result of the particular part of the engineering department in which I worked, (I got the jobs that were too difficult for others) and partly due to having a Masters in computer simulation. Every so often a lady called Glenda [yes really] would appear in my office door waving one or more 3.5" floppies with an evil grin on her face and the words "here is the latest version of XXX. See if you can break it".
My job was then to find out any limitations of the software, any bugs, and comment back on the new Windows interface. I would occasionally get free doughnuts for doing this.
That the reason for the call about it not working was because they had continued to use whatever their previous process was because they didn't want to use the new tool.
Then one day the powers that be took away whatever they were using before and they realized they were forced use the software he wrote but they hadn't the first clue how, so they told their boss it "wasn't working" to cover up for the fact they hadn't the first clue since they'd never even given it a look. Thus the support call after no calls for months.
I've seen exactly that scenario before - fortunately well off to the side. It is actually pretty common when you outsource your IT, or change outsourcing providers. They inevitably bring new tools for some processes, and the people who had been used to doing things the same way for a long time are highly resistant to learning something new just to accomplish the exact same thing. Sometimes they are even MORE resistant if the new tool actually delivers the promised efficiency gains the new provider was promising, because they fear some jobs will become redundant if greater tool efficiency means two people are now able to accomplish what twelve had been doing.
the people who had been used to doing things the same way for a long time are highly resistant to learning something new just to accomplish the exact same thing
And they are even more resistant when the "something new" is learning to use a massive, bloatware, probably has a "Kitchen Sink" app somewhere, pile of rubbish that's hard to use for the basic things you want to do - v.s. the "what we're used to" which is a simple tool that does the job it's supposed to simply and well.
Yes but in many cases they are themselves responsible for the kitchen sink they are saddled with.
95% of their job was handled well by the simple tool they've used before. When there is work afoot to replace that tool because the system it runs on is obsolete or doesn't comply with new regulations or doesn't integrate into the new accounting system or whatever, usually people will be asked what they'd like in the new system.
And that's when the 5% of their work that is awkward and time consuming with the old reliable tool comes up. Problem is, different people have a different 5%, so if everyone's wish list is granted then you end up with the kitchen sink.
Or these days the company isn't even developing it themselves. They are buying something off the shelf, and if their requirements list is long enough to capture the popular parts of everyone's 5% the only thing that handles it handles not just the 5% for your employees but the 5% of everyone in the target market. That's where you get the massive bloatware pile of rubbish. It is "what the people wanted" but not what any one person or even any one customer/company wanted.
I built a system for a very large telecoms company that hotdesked.
basically you had a large screen front and centre of the floor showing a map of all the desks, with logged in desks in red, free systems in green and logged in but Locked PC in yellow. Anyone coming in to work could find a seat almost instantly, instead of wiggling the mouse on every nearby PC until they found a free one.
orders came from on high that it should also check the login/logout times and when people locked their PC and when they returned.
All well and good until it turned out basically ALL the upper management would log in in the morning, lock their PC, sod off down the pub and return in time to unlock their PC at the end of their shift and log out.......
Suddenly I was told the software was "too network heavy" (approximately 3kbps for about 3 seconds if everyone logged in at the same time, with a total monthly "download" of around 1/2 a megabyte.....this was too much (in 2017)...so the software was shut down.
> "Have you read the manual?" Ray asked, remembering the substantial effort involved in its creation. "I just got a blank look,"
The manual should be IN/WITH the program. Even back to MS-DOS days, multiple programs, even freeware, had some or all the HELP in the program file. I recall raw text piped through MORE, and also highly formatted and indexed in-app help.
That's probably why my home heat/AC system has a flip-top plastic box on the side with all the manuals. "What nozzle size for 42k BTU?" Flip flip "0.025!" "Red wire or black wire?" "Black!" Not gonna trot upstairs and root through boxes for essential instructions when I am freezing.
The old audio equipment maker Alesis (RIP) made a pair of extremely user-friendly (for the time) MIDI music making devices, a drum machine called the HR-16 after it's amazing-for-1987 16-bit sounds and a MIDI sequencer called the MMT-8. Orbital used a trio of the MMTs as the heart of their live setup for years.
Both were loved by musicians for many years after their release because in the pre-internet age, Alesis had in their wisdom seen that a big flat empty spot on top was necessary to fit the PCB in the case, and decided to give it a flip-top with a little manual explaining all of the essential functions. So, if you bought one used for 50 currency units or whatever, you could immediately get to terms with it.
Akai had a help system in some of their sampler OS systems as well, which wasn't terribly useful but an impressive inclusion for one of the more arcane bits of technical equipment ever produced.
> Alesis had in their wisdom seen that a big flat empty spot on top was necessary...ecided to give it a flip-top with a little manual explaining all of the essential functions. So, if you bought one used for 50 currency units or whatever
https://i.ebayimg.com/images/g/JUwAAOSw5lRnES~m/s-l1600.webp
Some folks ask a lot more than 50 clams. Pretty good for its age and market.
I'm wondering if the user was ever shown the manual in the first place. They should have been given a copy of the manual at the start of employment, or at least some way of accessing it. I see users dropped into a job blind all the time. It isn't fair on them.If my theory is correct, this was a management/training issue.
I'm crap at documentation but I give it a try (I'm in the support team).
On our main document site, the top doc is the New starter guide which lists all the apps that support uses, with a 1-2 line explanation of what it does and how to install. Everyone in the team is encouraged to add new apps and strikethrough old apps when they are no longer used.
For each business group we have a page called Business Flow which starts with a "executive summary" of what that business does and how important it is (so if more than one business is screaming at the same time you know who to focus on). It then has a flow chart of the various components and how they are linked. This is invaluable when troubleshooting.
The next section is common issues - things that come up often or infrequently, or might might not be obvious. Again, everyone is encouraged to either add to this section or to tell me so that I can investigate.
And then the rest of the document is all the meaty stuff, how to install, what Devs to talk to, L2 troubleshooting, sql to run etc.
It's not perfect by any stretch but it does cover most cases. I still don't have enough time to document everything though.
To me an element of great design is orthogonally, if you do it that way here, you do it that way there if trying to achieve the same result.
I know you will kill me over this, but if there was some central command parser, with consistent ways of having the same parsing consistency across apps, api’s etc.
The horse has bolted and it just could not happen in the real world, but you can’t take my dream or next beer from me.
Jaysus, worked as Azure support (outsourced to the big bad LTIM, trust me, the company on the inside is worse than the support it provides to MSFT), this post gave me PTSD - amount of customers who would post sev A tickets when deploying/shortly afterwards without bothering to read the MS Learn, or even bother going through the bullet points in the emails was so staggering it burnt me out quicker than any other job I held. Because why bother checking if the VPN should have local/remote addresses put in correctly or cross-refing the peering setup against the tutorial when you can pull someone into an hour call to educate the (often also outsourced) team of 20+ even if they can't bother to change the setup for two weeks afterwards
Windows had, up to Windows 10, some screens in setting Windows Media Player, or hard drive swap files, that broke completely when you used another language. I mean, the kind of thing like the button disappearing down the window because it had no auto-resize or scroll bars.
If even "small and limp" can let such mistakes go into production, I wonder what anybody else pressed for time and with lack of QA would face.
It's not always user's fault, but something gets in the way, like screen resolution, or big icons ruining a layout. Manuals are good and all, but nobody can predict when something like that happens.
Ever tried a Windows 95 with too many program entries and low resolution? Some of those never show up in the Start Menu, and the scroll icons fail to appear in some modes you had back then.
The Register 
Biting the hand that feeds IT
Copyright. All rights reserved © 1998–2025
