Consultant misreads advice, ends up on a 200km journey to the Exchange expert Another Monday has landed with a thud – no doubt even more so for those of you in the States coming down from a weekend of Thanksgiving revelry. But it also means it's time for the latest instalment of Who, Me?, where Reg readers write in with their confessions of tech disasters to cheer you up. This week, we have a lesson in …
You ring the doorbell. You click the mouse. You boil the kettle.Oh, didn't you realize "boil" is onomatopoeic? Ah well. Carry on pretending to be an authority on English.
<pedant>I generally boil the water in the kettle, not wanting high temperature metal and/or plastic vapour floating around the kitchen.
I wouldn't say the word boil is onomatopœic - for me at least, boiling water doesn't sound like boil...boil...boil. You might argue that 'kettle' is a meronym for the combination of the utensil used to boil the water and the water itself (and also a synecdoche). </pedant>
For me, the vast majority of mice I have used emit a click sound when one of the mouse buttons is depressed, so it is entirely reasonable to use that as a description of the action needed to activate an on-screen button; just as when using a touch sensitive screen, the action people use to activate on-screen buttons is to tap the screen. I find silent mice take some getting used to, as I am accustomed to getting the auditory feedback. One of the problems I have with 'flat' interfaces is the lack of feedback when you try and activate sensitive areas. If you are not sure if your tap has been registered, you can tap several times to try and get a response, which can be less than useful if your taps are buffered and applied later.
One of the problems I have with 'flat' interfaces is the lack of feedback when you try and activate sensitive areas. If you are not sure if your tap has been registered, you can tap several times to try and get a response, which can be less than useful if your taps are buffered and applied later.
You'll like a portion of any web/html interface I design then.
Someone long ago (just when tablets were starting to get popular) complained about that sort of thing, and ever since I've used the 'onclick' functions to change the button and/or the border briefly to give a visual cue that it's been touched. Sometimes a colour change, sometime a border change (representing physical depression), but a change none the less to make it clear it's touched.
And this is why those of us who are technical writers (to a greater or lesser degree) struggle with techs(I'm one of those myself) and UI designers who adhere to a platonic ideal of how a GUI "should" be perceived versus how it's actually interacted with by those who use the thing. (By the way, that concept of a GUI is merely an analogy, and as such, subject to its own inconsistencies.)
The action you carry out when you select an object on GUI is not a "press" when using a mouse, it's a "click". This is what the users actually experience when they do the action (you're right that it's an onomatopoeic verb). Now, on touchscreen devices, you don't "click", but since you're not physically interacting with the thing on the screen either, I'd argue that you're not doing doing a (button) "press" either.
Personally, I prefer to just use the word "select" in all instances, as repetitive as it gets. If there are options, I often use the word "choose".
The adherence to platonic ideals when writing technical material without considering the audience is what has made it famously difficult to digest by the average punter, and even technical readers. Using the word "click" to describe the action of selecting something is not actually *inaccurate* in terms of eliciting the required action - it's an accepted colloquialism for selecting something on screen. As long as your phraseology isn't actually *misleading* the reader, it's always better to make documentation decisions in favour of proper understanding of the objective rather than pedantry. It is actually possible to write in a clear way (that might slightly elide some concepts) without losing the appropriate level of accuracy *for the audience*.
The GUI should be a metaphor for the physical world.
I strenuously object.
Maybe people thought that skeuomorphic design was a good idea when computers were new and users were terrified of using new concepts. But by now, imitating the physical world is more a limitation than anything.
Though I do agree that we need a better word than click, if only because nowadays people mostly tap.
A recipe I like is to write the techie explanation in the middle.
Above it, a simple note "for quick step-by-step guide, scroll down to <anchor>".
Below it, those step by step instructions. Any critical gotchas refer back to the explanation.
But then, the kind of instructions that say "click OK or cancel" don't feature in my world. I'll google when something is a bit less obvious than that.
When I first started writing code I was taught to do something that has long been very useful for avoiding this type of incident (I've "graduated" to writing user documentation and many other things).
You start with a "Header" that documents what the procedure does, what it requires as input and what it generates as output. It's been years since I've seen anyone writing or coding this way - I think this explains a lot.
You start with a "Header" that documents what the procedure does,
Absolutely essential while writing Java, but if you go quite a bit further you'll have something that anybody can understand and, better yet, YOU will understand if you need to tweak it in a year or five.
If you don't do all the above BEFORE you write more than than a skeleton class and methods then (a) you probably haven't thought the class design out properly and (b) for sure you'll piss off future developers.
The same goes for writing C except the the 'class' level stuff goes at the top of the source file and you need to check what's in your comments by running the code through your chosen documentation tool.
Last but not least, if the class or function package does anything thats even slightly complex write a test harness and a set of regression tests that get put into version control and/or backed up with thre code it tests. A PHB will tell you this is not necessary and/or a waste of time but IME he will be very wrong. A well-considered set of regression tests (covering simple usage, edge cases, and as much misuse as you can imagine) will save a LOT of wasted time and swearing. The test harness need merely take a line such as
methodname param1 param2 ... # comment saying what you expect
and split out the method name and parameters into an array of, say, strings and ints before executing an if.. then.. else.. totem pole which calls all the methods and displays all results interspersed with a listing of the test script. Dead simple: no conditionals needed because you can simulate that by the order of method calls in it.
If you're clever, you'll put all the script reading, parsing and printing into a driver structure that can run scripts against plugins that are specific to the class being tested and add something that compares test output with a set of expected results: a regression test pass is when the comparison produces no output.
"it's very difficult to write technical documentation that essentially boils down to a sequence of steps in a manner that does not sound robotic"
You're using a GUI. Get used to robotic-sounding instructions. If you don't like them, explain to the manufacturer that you prefer proper grown-up scripts because you don't like your instructions to sound robotic.
A member of another team was having some issues with data in an oracle database we host so a customer was having issues
Person spoke to the developers who are in a chocolate producing country with mountains
They gave her a script to run to "fix" the issue.
Turns out, they had provided a script that dropped the schema, suddenly, the customer could see no data, at all anymore - frantic scrabbling for restores and then replay all the data made for an entertaining day for some people.
A number of things came out of this
a) Support team having oracle admin rights
b) proof reading scripts that are provided rather than believe what has been given is right
c) an oracle DBA should be the one doing oracle related stuff.
d) remove oracle rights from everyone but the DBA's
Anon
One of my recent discovery is a chocolate made by Lindt with 99% cocoa. It is quite bitter (but I drink my coffee without sugar) but has such a strong taste that you still fill it in your mouth 30 minutes later.
The caramel and sea salt is great too, but so far I could only find it once.
@Olivier2553, if you're in the UK you can buy it mail order from Lindt
https://www.lindt.co.uk/shop/our-brands/excellence/excellence-dark-caramel-and-sea-salt
I also know you can buy it in Waitrose (and allegedly Sainsburys and Tesco but the butler doesn't shop at those establishments).
Data scripts...wonderful things! Some years ago I was working on a data migration for a corporate demerger (customer was an arse, objected to me doing terrible things like wanting to use encryption on files relating to HR and payroll records) and the functional techie came up with a script to do the extract. It looked good in theory but something I couldn't identify made my nose twitch so I ended up taking it to the lead Oracle DBA (who was the kind of BOFH that didn't believe anyone should be allowed near "his" systems: developers, support analysts and users alike) who read it through in silence and then explained in no uncertain terms exactly how much damage it would do to the platform if executed, followed by exactly how much damage he proposed doing to its author. We negotiated (he was okay if you asked him for things in the right way really) and I gave it back to the techie with the edited highlights.
While the techie was reconsidering his life choices, I decided to google the problem - only to discover the EXACT wording of the script (formatting and spelling mistakes included) in the very first returned site. Which is how I first discovered stackexchange.
Apparently, the only person in the world who actually worries when something says things like "Just delete the organisation" or "Just upgrade the entire domain" or "Just format the entire drive" is me.
Nobody else seems to actually care a jot about the implications, nor why an ENTIRE organisation has to be deleted to fix some problem.
Do people seriously do these things without question? I mean, it would always have raised red flags to me - as a junior I wouldn't have wanted to be sitting there deleting things in Exchange, as a senior I wouldn't want to be deleting organisations because something on the Internet said so (MS KB or not!).
I have a setup at the moment where we have an Exchange server on the domain, except the ORIGINAL Exchange server went ape and some idiot replaced it without cleaning up. The old one is still there, the old DB is still there, there are references in DNS to the server that no longer exists etc. And things like some of the special mailbox accounts only appear on *some* of the DCs. If you read MS KB, they say "just delete it" and/or "just re-run setup". Though I'm quite sure that works in many instances, I'm not an idiot to trust it.
Three times now, I've taken the whole domain setup down, and done everything recommended to get rid of that old server reference (even spinning up a matching-hotfix-level server, migrating mailboxes, trying to clear the origianl etc.). Three times it just trashed the domain or the Exchange setup. The only difference is a) I didn't do it blindly while in production, b) I snapshotted every VM on the network before I did it, c) I did it on an isolated copy of the production network, d) I was therefore able to see the destruction, try to fix ti, but then roll back the entire state of the test network in seconds, no harm done, without ever touching production.
The *proper* solution is a complete Exchange wipe-and-reinstall, but given that Exchange has worked quite happily in that state for years before even I came along, I'm going leave that until we need to upgrade/migrate anyway. It's not like I'll actually lose any mailboxes. Because I'm not idiot enough to "just press the button".
I often get asked to go into a charity to help them with their IT. The first instance was for a children's hospice. Can I just get rid of some icons from their desktop setups and change a couple of settings? So I go and have a look. Their systems are managed somehow. They have connections to remote-sites, remote-backups, and other things. Though I'm assured they are their systems "and other branches just work as our backups", and they have administrative passwords, I look a little deeper and the first thing I check is "can I undo any changes I might make?". I see that those backups aren't doing anything (0-byte log files, etc.). As they want me to make changes to all kinds of user settings that aren't just tiny little things, I don't proceed and dig further.
Of course, I could have piled in, made the changes, tweaked the bits and ran. But the deeper I dug the more I found. And then when asked why they wanted to make these changes and what work was done on the office machines that I was looking at, the answer: "Oh, it just collates and records all the end-of-life medication that we give the children so we don't make a mistake and accidentally kill one of them". It's not long before I'm backing out of there with hands raised, telling them that they need to get a proper support contract and someone to look at their entire system.
(Happy to take that responsibility, but not without a formal contract and insurance on my behalf!).
Don't be the guy who "just thought he'd try it". Be the cautious guy. The one who warns. The one who warns even when being yelled at to "just do it". And then, even if you're made to do it and it all goes wrong, you can just say "Oh... look... I wonder why I was cautious and told you that was a bad idea..."
We had orphaned an orphaned exchange server still hanging around for years every now and then creating a warning message when trying to do a task. Could never get rid of it without a complete new install and then copy across - which causes its own problems sometimes with X.400 addresses.
Nothing compared to very minor database irregularities which can cause days of issues. A couple of seconds of lost connection to an exchange mailbox data store can render untold issues. You'd think with a decent transaction logs and the original db it could quite easily sort itself out, but on the few occasions when it happened I had to do a Hard-Fix on the database after trying for days to do the standard recoveries which caused significant damage to the mailboxes (although the db became mountable again) and the only fix then was to move the mailboxes and allow a very large number of corrupt messages to be skipped.
SQL has always been far more robust to data errors in my experience.
Only a couple of times in my career have I been told "just do it!" by a manager in the face of my warnings of dire consequences. Both times, I've answered: "I will do as you ask, but I will need your request in writing as well as an acknowledgement that I warned you about X, Y and Z". I was quite happy to tell them that I needed it to cover my arse when things inevitably fell over. Most of the time, the managers' requests mysteriously went away. For the one that didn't, the manager did at least stop and think through what he was asking before pushing ahead.
"things like "Just delete the organisation" or "Just upgrade the entire domain" or "Just format the entire drive" "
Personally I find that the word "just" immediately rings alarm bells. It implies a confidence (which is almost always utterly misplaced) on part of the speaker/writer that this is a trivial thing requiring little to no effort on your part, and also sneakily implies that your unwillingness to do said thing is due to incompetence, bloody-mindedness or both.
Just start paying attention to it, you'll be amazed at how often it gets slipped seamlessly yet completely unjustifiably into a conversation.
"Just". Not just an IT thing.
Anyone who says "just do.." hasn't thought through/traced the consequences. No job, however small can be guaranteed free of unexpected complications.
As in, "You can just move the shed to that side of the garden" . Which is when you find that under the shed there was a two foot deep pit, the base of the shed is rotten and the other side of the garden is rather less even than it looked..
Or " You don't need an electrician. Just replace that electrical socket". Fine, until you find that behind the socket there's a tangle of wires that are somehow, just, hanging into the back, but will never go back in again once moved. (I'm not an electrician, I have changed sockets, but I do know a good one to call if I have any doubts whatsoever. And I do).
Or " You don't need an electrician. Just replace that electrical socket".
In many countries it's a criminal offence to do that for "hire or reward" if you don't have the appropriate pieces of paper - so having the order in writing is absolutely critical to ensure shit doesn't flow downhill.
Well, I'm sure he wasn't able to make the deposit he needed to do, so it seems to be kind of an own-goal there.
I expect making tellers/retail clerks pissed off will be its own karma, as I find that making them happy reaps rewards for several years down the road. I've been given free lattes and such, months after helping someone get the job done in a broken situation.
"And why do tellers have the ability to bring down a whole system? No permission control?"
Either the architect in 198X didn't think it's would come up (seriously, just don't tell them the command exists, they'll never type that by accident, right), or they did and their manager said "we don't have a week for you to code in permissions".
A lot of what we now see as obvious best practice was learned the hard way.
"A lot of what we now see as obvious best practice was learned the hard way."
Things such as "don't launch those solid boosters in freezing conditions" spring to mind.
Unfortunately despite repeated warnings about stuff which seems obvious in hindsight, 'obvious best practice' is often scorned as "too difficult" or "unfeasible" until after a lot of damage has occurred - and even then you'll find someone who thinks it's too much effort.
The Register 
Biting the hand that feeds IT
Copyright. All rights reserved © 1998–2024
