Spoilers in Tech Docs!
For once I wouldn't mind a spoiler, instead of instructions that read "but first.... " after you've already taken a first step!
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 …
I've been on both ends of this, both having to write procedural guidance and follow rarely used stuff for e.g. end of year processes. I can sympathise with the authors, 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. Your intiial draft often ends up as "select this", "click this", "click this", "click this"... and the resulting prose sounds awful even if broken up by bullet points or numbered steps. It's also quite difficult to follow since all the steps seem so much alike and can be confused - at this dialog do you follow the "click OK" step or the "click cancel" step?
You do try and mix up language and sentence structure as much as possible but there are rules that you are best rigidly following, such as as here, alway presenting steps and information in the order it is needed. Out of order even within the same sentence, such as "Do this after having done that..." is guraranteed to cause errors because people will have done "this" before reading ahead the few extra words which cover "that".
I hate the expression "click this". "Click" is an onomatopoeic verb or noun; "click" is the noise that a mouse or trackpad button makes when it is operated.
The GUI should be a metaphor for the physical world. In a GUI, users press buttons, slide controls, grab objects or select objects etc. When visiting friends, do you click the doorbell or do you press it?
While true you have to remember the target audience for any documentation. You'd be surprised how many people ask "what does press button mean?" and when presented with the answer reply "well why didn't you just say click it then?"
Your average user associates "click" with the sound the mouse makes when they press the virtual button on the screen. It's all very Pavlov, but yes, if you want to get your point across to the average user it's safer to say "click button x" than it is to use the more logical "press button x".
"click" with the sound the mouse makes when they press the virtual button on the screen.
My mouse click has never in over 30 years of using GUIs resulted in a sound effect when using "virtual buttons". They USED to invert the left & top with bottom & right to visually indicate clicked or held down. Sadly mostly the now don't. "FLAT" is stupid.
Ironically many of the "flat" buttons in Windows 10 do actually change in a looks like they are being pressed way if you click on them.
The way they push in also changes according to where you clicked, or if you moused out and back in, where the mouse re-entered. Click on the left and the left side is pushed in more than the right. Re-enter from the bottom and the bottom is pushed in further. Re-enter from the top the top is pushed in further.
"They USED to invert the left & top with bottom & right to visually indicate clicked or held down. "
I've heard that being called 'Slab in' i.e. trying to visually show that the button has been pressed in. The strange thing is I sometimes find Windows does change the icon to 'Slabed in' but doesn't do the action!
Also my mouse (pointing pebble a better name?) has a tactile click on the buttons or wheel press, none have ever made an audible click. The so called "haptic" feedback on phone virtual button presses is useless, nor has any phone had a decent click sound. Some manage the DTMF tones on keypad.
Tutor: Press button X!
Student: [Reaches up and touches the screen]
Tutor: No, no, that won't work. It's not a touchscreen display. You need to press it with the mouse.
Student: [Lifts mouse up to the display]
Tutor: No, no. Good grief. OK, let's start again! Move the cursor over the button!
Student: [Reaches up to the screen, touches the blinking cursor in the command terminal, then tries to drag it over to the X button]
Tutor: Oh for the love of... Look, just move the mouse pointer over the X button by dragging the mouse across the mouse mat then briefly pressing down on the left mouse button!
Student: Oh you mean "click the button"? Why didn't you just say so?
Tutor: [Shoots himself in the head]
Sometimes you just have to accept that language evolves to reflect the way it is actually used by the majority. This is exactly why dictionaries are continually revised.
NB The above scenario is a real example drawn from my personal experience (although I didn't actually shoot myself). The "student" in question was actually my elderly mother, who I was coaching over the phone, desperately trying to retrieve somebody's contact information from my PC. This was many years before smartphones and cloudy storage.
do you click the doorbell or do you press it?
Where "press" is a physical action which involves pushing on the doorbell button.
Using "Push on the OK button" may be fine for a touch screen but not so clear when using a mouse.
"Click on OK" is a good enough shortform for "Move the mouse pointer over the OK button and push down on the mouse button which will make a satisfying click sound".
I had a quick look at the oldest documentation I could find for GUIs -- Lisa 7/7 for the Apple Lisa 2 -- and it uses terminology similar to that described by Jason Bloomberg. It actually says things like "click OK".
So the convention has been around for at least 34 years... It still bugs me.
"do you click the doorbell or do you press it?"
Neither, I ring it. You should use the vern that describes the ****ACTION****, not an incidental implementation-specific method of getting to that action.
You select YES, you don't click on YES. You may not have a clicker, your clicker may not make any clicking sounds, you may not want to use the clicker you may want to use the keyboard or a touch screen. It's this american moronism that does things like call a mobile phone a one-specific-implementation-of-a-mobile phone, and "buzz saw" - what the hell is a buzz and why and/or how would I want to be sawing it?
You select YES, you don't click on YES.
"Click on YES" is shorthand for "click the (primary) mouse button while the pointer is over the "Yes" button on the screen". As English Usage it's not lovely, but it's pragmatic and most people -- most people who know what a mouse is, anyway -- know what it means.
Note that you can "select YES" by moving the focus to the button control with the caption "YES", but that doesn't activate it, you have to press the space bar or Enter key as well to do that.
... and "buzz saw" - what the hell is a buzz and why and/or how would I want to be sawing it?
A "buzz saw" is a kind of saw. What kind of saw? The kind that buzzes. "Buzz", here, is used as an adjective to describe the kind of saw being mentioned, and will be understood by anyone who knows what a buzz saw is.
If you expect every adjective+noun pair to work the same way as "fly trap" (a trap for trapping flies) as you seem to expect "buzz saw" to do, then you will find many common phrases -- such as "hot tap", "front door", and "light bulb" -- rather confusing!
"You select YES, you don't click on YES."
Drop-down list, Run the pointer down the list. As it traverses the list it selects each item in turn. Leave it on the item you want. Many (?most) people would reckon you'd selected the item but nothing will actually happen until you take a further action which, at least on this laptop makes a loud, and AFAICS, purely mechanical clicking noise. But don't call it a mouse pointer 'cause it's a trackpad.
If you think technical documentation is bad for PCs try writing process documentation for machinery. There's a reason the document seems to assume the user is a complete moron, occasionally the user IS a complete moron. But if you don't take into account that you need to tell a user not to touch a chrome plate that's heated to 200C and they then burn themselves it's the document writer to blame, not the idiot with no common sense.
You need to get over it. Language evolves.
Click may have some historic association with a sound, particularly in an era when computer devices had horrible artificial "click"s that were supposedly reassuring to people making the transition from mechanical typewriters. But that's now historic, and (in a computing context) the word "click" is now an action.
"You need to get over it. Language evolves."
No. Evolve doesn't mean what you suggest.
If you apply Darwin ideas, a word would change to survive in usage for the mere purpose of survival. Words aren't organisms. Words don't evolve.
People change and language changes. And sometimes people get it wrong.
Failure to comprehend the distinction between uninterested and disinterested amazes me. Are we supposed to toss away the difference because the two words are "about the same"? 'Cos some people muddle them up?
Uninterested: I live in Wigan and follow Rugby League. I am uninterested by Manchester United because I have no interest in Association Football. Not bothered.
Disinterested: Owing to my acute eye sight, I earn a living as a tennis umpire. The sport bores my tits off so I am uninterested. I watch the players and when I proclaim that somebody played a foul, I am disinterested.
Evolution isn't change.
> No. Evolve doesn't mean what you suggest.
Evolve, as you note, didn't originally mean 'simply change'. But it *is* how very many people now use the word.
(and yes, some such changes drive me nuts. But many folk use new words or forms for successful communication; so much so that they are often added to the OED - https://public.oed.com/updates/ )
None I've had in 40 years had any sort of "artificial clicks." Some decent keyboards had a faint mechanical click. You COULD turn on an artificial keyboard "click" on some BIOSes, but I never knew anyone that did and I knew plenty of people that had used typewriters and still used them in parallel up till start of 21st C for specialist tasks.
"You need to get over it. Language evolves.
Click may have some historic association with a sound, particularly in an era when computer devices had horrible artificial "click"s that were supposedly reassuring to people making the transition from mechanical typewriters. But that's now historic, and (in a computing context) the word "click" is now an action."
And I still "dial" a phone. My car horn "honks". A repetitive person still "sounds like a broken record" (coming back, I guess since hipsters discovered vinyl). So, yes, I may not move a mouse, but I still understand that moves a cursor to a specified location.
" When visiting friends, do you click the doorbell or do you press it?"
Or... Like I do... Ring the doorbell.
It's pretty much well known by everyone that "Click on" means move the mouse to that the pointer is over the correct position and depress the left button. Good lord, we're a pedantic lot sometimes (I certainly include me in that).
This post has been deleted by its author
do you click the doorbell or do you press it?
At one of my friends' dwellings, I pull the porcelain handle hanging down from the porch. The handle is attached to a wire cable in a conduit, and somewhere in the depths of the house a physical bell on a spiral spring jangles. Another friend has beside the entrance door a sprung knob which you pull and release to set a bell ringing. That confuses a lot of people, even though the brass around the knob is engraved "Pull to ring".
I remember visiting someone in a flat somewhere on the continent, and the doorbell was a rotary device - you rotated it, and a bell on the other side of the door, much like an old-style bicycle bell, trilled away. A similar device I have seen is a clockwork doorbell, which has a conventional button to push, but which is wound up by turning the bell on the inside of the door. If you forget to do this periodically, it falls silent.
I have yet to see a doorbell operated by a lever, but I expect it is possible. Or even a pneumatic plunger to operate a whistle.
"Just dial 555-1212"
Has anyone seen a dial telephone recently? I have an old dial telephone and my granddaughter (13 years old) struggled to make a call on it (as did a full professor at my college years ago). My 3-year old granddaughter loves the dial phone to play with.
If there arethree things I hate in documentation its the use of obscure technical language which can be ambiguous to the reader, the use of over complex language when a simple phrase will do and grammar zealots.
We are not writing works of literature, these are technical guides, process documents and user instructions, they should;d be clear and concise and 'good enough' to do the job.
If a document is clear, unambiguous and correct then it is good enough, I'm not concerned whether the correct use has been made of the Oxford comma, or whether a technical team member who has worked hard to produce a good product has split an infinitive. Also think about your audience, not just in the language you use but also in the length of what you write. whilst a header explaining the purpose of a process may be appropriate for a design document its unlikely to be appropriate for the work instruction to be followed by a harassed agent in a call center who just needs the instructions (or script).
And if you ever do deliver products into a call center be sure to leave enough time for several reviews while the call center manager localises the instructions to suit the team culture. This is not the manager being difficult it is making sure that every thing agents see follows the house style and flow so mistakes are minimised. Your part of the review process is not to try and 'correct' the house style it's to make sure the technical elements remain correct.
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
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
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.
Anecdotally, I burn any bridge that I never intend to set foot on ever again, and never want anyone else to, and which I'm totally in a position to do that without negative consequence.
For example, if leaving a job that you so desperately detest because of serious issues with the way they deal with people... burn the bridge. You will never want to work for / with those people ever again, no matter where they may appear in your life.
"He might be the interviewer on a future job"? Good. Then the second we see each other (or each other's name), we can nope the hell out of there and save both our time, effort and money on anything further.
Merely don't burn your bridges WITHOUT CHECKING FIRST. The same way that you wouldn't delete a backup, or pop out a hard drive from a machine, or power off a server, before checking that you had, in fact, got the right on.
This post has been deleted by its author
You beat me to it!!
I had exactly the same paper on a course many years ago when I were a lad and new to IT/Training/Support.
Hate to say it but I was the only person in the class of about 10 or so who did actually read it all the way through.
The other fun exercise we did was trying to tell someone how to strike a match from a closed box on a table between us with the person striking the match only doing exactly what you told them. And of course the instructor on the course had ensured that every box was upside down!!
I know a secondary school science teacher who has literally encountered dozens of pupils who have no idea how a match works or how to light them and are shocked that it's actually a real flame that burns their fingers.
In one way, I see that as progress (kids aren't exposed to people smoking), in another way, it is quite worrying that they don't understand how something quite basic works.
Many years ago, in the last-but-three decade of the last century, a colleague told me of a Systems Analysis course he had attended at ICL.
Everyone sat around a big table. The presenter dumped a huge box of mixed bolts on the table and said "sort that out".
After an hour or so, when the bolts were sorted in order, he said "Well done". Then he picked up the single four-inch carriage bolt sitting on it's lonesome at one end of the collection. "But I only wanted this one".
The lesson being that the course was going to be all about discovering the right questions to ask when given a user request.
I believe the Systems Analyst job position has largely died out. A shame. Many of the issues we read of here at El Reg have to do with not asking the right questions.
Scope creep is a whole 'nother issue and has bee with us since Gak Eisenberg demonstrated his perfectly fit-for-purpose hammerstone to the tribal elder and was asked if he could add an antler handle to it and maybe use a more glittery rock.
To some extent, that's true. Still, there are situations where you can't get people to tell you why you're doing something. It's entirely logical, if told to sort a box of bolts, to do so. After all, if the person telling you to do that just wanted the biggest one, they could either have taken it out at the beginning or asked you to find one with the required specifications.
Sometimes, you want someone to just do what you ask of them rather than to believe they can do it better if only they know everything there is to know about what you're doing. For example, if I ask someone to find the most cost-efficient machine with a set of specifications, I only want them to look at the options, eliminate those that have worse specifications, and choose the one that has the lowest cost (perhaps taking into account other things that they can definitely ask me to elucidate). I do not need them to question me as to whether I want more power because they found one that's only a little more expensive, nor do I need them to suggest that we'd probably be fine if we bought machines with less memory. I set forth the specifications and gave them a task. If they're going to change the task instead of just doing it, perhaps they should be doing my job.
The same is true of software jobs. I cannot deal with every part of a project team thinking they can and should be designing a better system for every component. Their system for some of it may in fact be better than the one we're using, but if it doesn't integrate and won't without doing a lot of work first, it can still be worse. And if each team or team member comes up with their own version that doesn't interact, we spend forever getting things back together. That's why abstraction is so key; figure out the best way to do your job, not the best way for someone else to do theirs or even for you to do someone else's job. If you have some improvements to suggest, go ahead, but don't neglect what you're supposed to be doing just because you don't like someone else's work.
I agree with the comments here although I have worked with fellow techies take things way to far in the caution direction leading to nothing getting done and being stuck in a perpetual risk / change loop. While things should be planned, risk is not the reason to not do something.
If you don't do something, you end up with systems that are 10-15 years old because they just run and you run out of support. Then you have major upgrade issues as most of the time you have to step upgrade to versions that also aren't supported.
In my mind it is all about balance.
"If you don't do something, you end up with systems that are 10-15 years old because they just run and you run out of support."
The roles of managers are to keep the stuff created in-house up to date and to keep the out-of-house stuff within bounds of support. If managers aren't doing that, you are in a problem organisation. Companies can run ancient systems for years -- as long as they are properly managed.
It is unlikely that any of your positive actions -- at sys admin level -- will change organisational direction unless a manager is on your side. But they might be the right things to do.
Exactly, that annoys me too. Especially the ones that say in the middle "Leave overnight in the refrigerator."
It seems to be the root cause analysis here is a badly worded document. It should start "This only applies if you have a single Exchange server. Other requirements before proceeding are..."
I used to tell our PHB that I could NOT write training manuals because I knew how the software worked. Technical authors are really needed.
I used to tell our PHB that I could NOT write training manuals because I knew how the software worked.
If I had £1 for all the managers who didn't listen when I told them that I could not test this piece of code because I was the one who wrote it, I'd be able to employ someone full time just to empty the ashtray in my other Lamborghini.
My documentation explained that an automated process would clean up some artefacts from the installation process within 15 minutes. The artefacts were harmless but annoying. Users didn't see them. I was cleaning up because I am conscientious. And you have other things to do on the PC which take more than 15 minutes.
My documentation explained that IF the process didn't clean up (2% failure rate), THEN the next run would do it. Or the one after that. ELSE that fails too or you are in a hurry, in which case you can delete the files manually.
So why are you on the phone after 16 minutes asking what to do?
Because that's the kind of instruction that never fails to confuse its audience. First they get "you don't need to" followed by "but you can if you want" and that invariably results in "now should I or should I not?" - I'm pretty sure the syndrome even has a name but I can't recall it. I do understand that this is technically not a fault in the instructions themselves which merely go to out of their way to fully describe all possible options and possibilities, but the fact remains their effect on the user is to cause confusion and paralysis unless said user is unusually adept at this sort of thing. Which is exactly what one should not and can not ever safely assume.
"Because that's the kind of instruction that never fails to confuse its audience. First they get "you don't need to" followed by "but you can if you want" and that invariably results in "now should I or should I not?"
IF my audience doesn't comprehend THEN my audience has failed computer logic, and we need a chat.
I don't like bossing people around.
Anyone that trusts what the internet says blindly is, frankly, asking for trouble.
Even technical advice for problem solving, although often helpful, is often resolving a problem that is only "similar" and therefore the solution may either be ineffective or add to the problems you have.
I rarely find advice that directly matches the situation I encounter, or relates to the same combination of software versions I am running.
Unless what you read is close to, aha, I would have thought of that eventually, you may want to get a second opinion...
Outside the techie world there is a great deal of "advice" which is positively malicious too, and plays the gullible to brick their devices, and remove their data...
Anyone that trusts what the internet says blindly is, frankly, asking for trouble.
Some years ago my dad, approaching the end of his life, thought it would be a good idea to write down all he could remember about his side of the family, annotate old photographs, family collections, etc. I helped him draw up a family tree and organised a mostly-sufficient filing system for his notes. One day he read an article about genealogy software, so he called me and I bought a subscription to one of the more widely recommended services, installed the software on my laptop and took it along next time I went to stay with him. We spent a couple of days doing all the research we could, trying to clarify names and dates and places and match them up. All of a sudden it fitted together and we were able to slot in about six generations from the late 18th to early 20th century, about 80 years further back than the oldest surviving photo or letter. We were well chuffed with ourselves.
But something didn't feel right about two connections in the 1880s and 1890s. It took a while, but we eventually got to the bottom of it. One of my cousins had researched the family a few years before, and it turns out she'd made a mistake with those two connections, linking us to a family who just happened to live in the same area (but one census apart) and have two eldest children with the same comparatively uncommon first name as a great-aunt and great-uncle my dad could remember from his childhood (our surname is reasonably common in that area). The software had found my cousin's work in one of the databases it monitored and from then on effectively presented it as verified.
...where the engineer has "assumed" knowledge but not mentioned this. I understand sometimes you have to assume knowledge, but fing put that at the beginning. Don't skip steps that you "assume" a person that's never seen the guide before, for software they've never seen before, will "work it out".
That's why I like to do my guides as if you've never done it before. You know IT but you've never followed this guide before. I put every single annoying step.
The most false guides I've seen are in gaming when in the chat window. Back in the Vietcong days, if people had issues and asked in the chat. You'd get several knobs telling them to do "Alt F4. That will fix your issue".
Haynes car maintenance manuals were fond of a step "remove ...." - without the essential details of how the thing is held together.
The Haynes Series "A" Range Rover manual simply said "remove back seat cushion". After much struggling it was lifted out - with a now bent flange that required the cushion being slid outwards to disengage it first.
I write technical instructions as part of my job. I have a standard outline for all of them:
1. Safety permits, etc. needed
2. Notes on safety hazards and how to mitigate them.
3. Equipment and tools needed (aside from standard hand tools)
4. Actual procedure
The procedure section frequently starts with "Schedule work with affected department" or similar statements. Any important note about what NOT to do is on its own line, at the appropriate point in the procedure, with the word NOTE: (or occasionally something stronger) in front of it.
Write your procedures so that a brand new employee can follow them!
The document that got 2/3rds of the way through post image setup of a server, then presented a screenshot of "Continue..... " "Yes" "No", at the very bottom of the page then had 2.5 of blank pages before it resumed with " graphic of a stop sign & text saying STOP - Do Not Press Yes At This Time".
By which time it was too late & you had to reimage the new bank server at 12.30am all over again.
Fixing a leaky master cylinder I followed the instructions in the Haynes manual to remove it, then got to where it said "using a pair of circlip pliers....". Did I have a pair of circlip pliers? No, I did not.
I had to put it all back together, drive to the shops and buy some, go home and dismantle it all again. Bugger.
"IIRC which can come in two varieties depending on whether you need to expand or contract the circlip to fit it in place."
In the application of a mini brake cylinder (not a master cylinder which is bolted to the bulkhead), a slave brake cylinder retainer clip clip should be removed by a blunt-ish screwdriver. Maybe by needle nose pliers. Not your decent screwdriver for obvious reasons.
When I was about 12 my parents bought me a cheap tape recorder for my birthday (this was a couple of years before cassette recorders became ubiquitous, so it was a bit of a rarity). I bounced down to breakfast to find the gadget positioned beside my place at table, not wrapped or even in its box, but with the instruction booklet on top.
Wasting barely a moment on the Book of Words I pressed the "Play" button and my father's voice emerged from the small loudspeaker saying:
Read the Instructions FIRST!
Obviously, the article should have had the bit about "Only do this is you have only one Exchange server" at the beginning.
This reminds me of the old joke about the guys disarming a bomb with one guy reading the instructions to the other.
"Unscrew the cover!" "Okay, got it unscrewed."
"Cut the red wire!" "All right, I've cut the red wire. What next?"
"But first, cut the blue wire..."
------------------------------> See Icon
I recently pulled an Old Man Idiocy when using TOAD (an excellent tool, but like all tools very dangerous in the hands of the unknowlegeable, forgetful or just plain lazy - last one applies in this case).
Asked to move an Oracle package from a test database schema into our production schema I proceeded to pull up the package in TOAD, did a create script to the clipboard, pasted it into the editor window in the target database session, edited the code to change the schema name and ran said code in the production database that night as requested.
Next day no-one could access the package code. It seems some witless dolt had removed all the permission grants and synonyms from the package.
Turns out I had neglected to double check the check-boxes on tab in the create script pop-up that controls the generated code closely enough, and had neglected to notice that the generated code contained the dreaded "drop object" syntax.
Not only that, I had neglected to recognize that that had happened when I did the code edit for schema name change. I mean, it was only hiding in plain sight on bloody line one.
Unfortunately, I rather like all the people I work with now, so I was forced to do the Bonehead Dance and wear the Pointy Hat of Not Being Smart instead of shifting blame to the intern or new hire as per industry standard practice.
"And that I learned always read an article to the end before implementing the procedure."
Yup. ESPECIALLY if said documentation originates from the USA, where the important bits are almost always at the end.
EG: technical procedures for adjusting Harris 15kW shortwave transmitters. When you get to step 23 they tell you 5 steps you should have undertaken before step 1, 3 more before step 6 and helpfully inform you that if you haven't done these and taken 6 crucial measurements before step 3, you'll need a vector analyser to recover.
The one thing I learned from my most pedantic, most arsehole, most annoying, most fucking terrifying profs was "READ TO THE END OF THE INSTRUCTIONS. DAMNIT!". There is a reason those fucking goatfucking twats write exams that start "read to the end" and end with "only do question 1, which is "write your name"". That's exactly to avoid situations like this. Those profs were attempting to impart a lifetime of knowledge in an all too short timeframe. As Stargate taught us, the young do not always do at they are told. Learn from this.
Biting the hand that feeds IT © 1998–2022