Brown M&Ms, or Why No One Reads the Manual(blog.nuclino.com) |
Brown M&Ms, or Why No One Reads the Manual(blog.nuclino.com) |
During my final week when I was doing code handover I sent an email around the company pointing out that the wiki would answer most of the questions they might have about the apps I worked on.
Three months later my phone starts ringing. I was in a new job so I didn't answer, but they kept ringing. Then they started calling my wife as she was listed as my next of kin. My wife also didn't answer as she was with a client. After a few hours, my wife picks up the call and texts me that my previous employer was desperate to speak to me. So I called them during break and after a bit of an ear bashing I was informed their whole warehouse system was down and all business had stopped.
After a bit of diagnosis I realised that they had fallen for the first gotcha I listed in my docs, they deployed the wrong DB driver. I asked why they didn't read the docs. They responded "what docs?". I explained that I sent an email round before I left with guidance on the app. Rather than apologise they berated me for not doing more to alert people to the existence of the information. It was that attitude that contributed to me wanting to leave the company in the first place.
I think the moral is that no matter how good your docs, some people will always ignore them even when the world is collapsing around them.
you actually helped them? Hang up, charge your emergency hour consultant rates, and tell them you're available once they sign the agreement.
I'd rather be known as the guy who helps than the guy who is rude about consulting rates.
When people treat you that way, you politely say "If you want my help, change your tone."
If they don't, hang up.
That was the first time they called.
I made a perfect confluence-wiki, for every server a page, for every application on that server a sub-page.
The Code-repo-links the config's the howto's everything was in there, the second time about 2 month after i went for the other job, they floded a Oracle-Db, called me and asked really rude what a shit installation i made, so i asked for the server pointed them to the Wiki-site and the first sentence boldly written said: DEV-VM -> DB-scheme-migration (DONT put DATAS IN, 20GB-DISK)
My docs clearly stated that you should not update the driver unless you were willing to rebuild all the other projects as well. I could only deploy one copy of the driver file, so it had to be the version all the different parts of the application were expecting. It was an old app, whoever started development on it didn't know about repositories and DB singletons - there were DB connections all over the place.
The annoying thing is that the .net error message they were getting actually stated what the problem was in fairly clear terms, yet they still called me.
I really enjoyed this read. I think it contains actionable suggestions that I will incorporate into my job. Consultable documentation, all in a single location sounds like an improvement over what I have now.
The focus of my approach has been a bit different so far: since I know that nobody reads the manual, I strive to make the manual short: "Run this one command and it will do everything for you." My thinking is also that it lowers the bar of skill for new hires. There are some unfortunate consequences of this:
1. Maybe we don't want to lower the bar of skill after all (maybe we do - good workers are hard to come by where we are).
2. I am something of a single point of failure. If I go, I'm sure things will still get done, but it won't be done well (very subjective of course).
Anyway, I'm excited to try and improve my processes to make it easier to grow.
This is also why we've never Dockerized. It masks too many issues and no one seems to have a clear understanding of how all the garments are stitched together.
Few people took any notice of it.
That nonsense would last exactly as much time as it took me to recognize the words and to hit "end call". The phone is for my convenience, not theirs.
Minor tangent, but that got me to wonder: would that be legal under the GDPR, which only allows you to use data for the (legitimate) purpose it was collected for?
In this case, they gathered next-of-kin info for (I assume) disbursal of benefits when the employee is dead or incapacitated. “To find the employee after he quits” would be out of that scope, then, right?
In Ireland next of kin is purely for cases where the person has been incapacitated/hurt and someone needs to be told. Nothing to do with dispersal of benefits etc. There's a separate process for all that.
Not actually getting paid/having an employer there can be quite liberating...
Since nobody who ever writes me is a customer, and I am not getting paid anyway, I am more or less free in what level of politeness I apply. I usually try to model my response after the initial requests I receive - taking into account other factors like people who might be genuinely upset; or confuse me with the person who actually uploaded a piece of content.
We have users from all over the world, and it's rather interesting to see particular patterns/attitudes with certain types of locales.
For example, Americans - by and large - are too lazy to read the few lines of text on our contact page detailing what information we need to address what kind of problem, and often are rather rude from the get-go, and really like to threaten with their lawyers (plural!) in the initial email when it comes to copyright or related issues. This then leads to me asking for the missing details, followed by a lot of them demanding to talk to my supervisor, to which I then point out that they are not our customers and that being rude or even outright insulting the only person who could potentially help them (for free) isn't maybe the best idea they ever had... And if the supervisor demand came up, I point out that I do not have a supervisor, I demand to talk to their supervisor instead.
It would be unfair to only unload on Americans, tho. We got a lot of Portuguese users, and tickets from the Portuguese are even more rude on average and of course nobody bothers to read the instructions, tho nobody ever demands to talk to my supervisor. The French are polite but like to make outrageous demands, but seem to read the instructions. Germans are "professional"-polite but tend to write LOOONG emails, and when it comes to copyrights usually cite a lot of completely unrelated laws, but again read the instructions. Middle/South Americans are usually polite but constantly think the Subject line is where all their text is supposed to go, and do not read the instructions. I'd say the most pleasant people are the East European (mostly Polish and Russian) people who write me... I don't remember anybody outright rude from East Europe ever, tho the language barrier - our website is English only incl the instructions - is often rather obvious (but I will not fault anybody for that, of course).
Point being: the level of RTFM in my limited experience differs quite a bit depending on locale.
Same principle as rubber duck debugging.
Common myth, but actually not true. Joe Rogan has 3 hour long talks with people and is one of the most popular media figures.
The real truth is, most information sucks (it's both useless and boring), so people tune out. Improve information, get more attention.
I've crimped so many RJ45. Can't count.
Before CAT6 it was simple. After CAT6, all vendors starting produce their own.
This is my best manual all time. I love Penduit manual.
http://www1.panduit.com/heiler/InstallInstructions/N-COPN295...
The fact that some people do not read makes a canary useful. I guess the title making a rhetorical point just flips my logic sensor.
Not sure if that would just piss off users beyond toleration, but it's an interesting idea.
In my experience one of the big problems (I just had a call from one of my users demonstrating exactly this point) is that often there is a disconnect in terms of vocabulary.
What the business calls a "refresh" of System X123 could be any of "full copy from prod of the whole X123 data", "can we please just import the subset of data I created in X123 Test?", "X123 provides a sort of materialized view of the sale prices to Z567, but it seems that the view is outdated, can we please refresh that"?
This happens (albeit less severely ... "usually") inside IT itself at least when the organization gets over a certain size. So dataset are named with their content, but the actual content might change scope or the part which is more relevant varies for each consumer, therefore both the provider and the N consumers tend to refer to the same thing with slightly different names while the "correct" name is already used for something else in different context (e.g.: "Sale prices" - is it now? future? historical? only for agents? only for a specific country/market...?).
Even just having a single, unambiguous lexicon would help a lot (and would make the "searchabilitly" a bit less mythical) but I don't see this or similar points addressed, while apparently the detail of the sound and light equipment deployed by Van Halen seems to definitely require some space.
(Imagine an ERP system built in UK and adopted and customized by a French company, for example: IT would probably use 20% of French terms/names, the rest will be in English... Business will do the opposite).
And, reading the docs looks to an external observer exactly like playing video games or browsing facebook all day. Modern "agile" organizations dedicate two or three watchers to each actually productive employee to "make sure" that the productive people are actually being productive. This means that the only time spent on tasks is spent on tasks whose outcome can be quickly, easily externally observed.
That this necessarily produces a substandard product seems to be unimportant.
So of course in our status meeting yesterday I had to say I hadn't accomplished anything. In the long-term it's good to have someone on the team who really understand MongoDB. In the short-term it looks like slacking off.
- Of course my conclusion after reading about MongoDB queries was to decide that I wanted as little as possible to do with MongoDB queries and am going to avoid them at all costs.
I opened the manual to find it was many pages of legal text and just one phrase of instructions: "hold button for 5 seconds until light is blue" and that failed too.
I mailed support and the instructions then came back as "hold for 20 seconds, until light first becomes white, then blue", I simply mistaked the white led as very light blue.
This is why people don't read manuals!
You write "hold button for 5 seconds until light is blue", and someone will hold the button for 3 seconds until it turns white and ask why it's not working.
I try to set an example by providing copious context but I don't feel like others imitate me. Sometimes I think I'm the only one who has a theory of mind.
It was for this exact reason. Someone filling out a bug without collecting logs was usually missing a lot of vital information needed to diagnose and fix the bug.
At the same time I also thing its a little overly complicated.
Used to be an (amateur) sound tech & realised pretty fast that stage stuff is an industry where its incredibly easy to tell who is on the ball and who isn't.
I find it very hard to believe that an experienced band can't just stroll across the stage with a can of beer & know the answer 20 seconds later. No M&M contracts needed.
Still cool story with a good message though
2018 https://news.ycombinator.com/item?id=18643258
What error codes does the program return? How about some non-trivial examples of use?
And does the man page actually document the software? All the switches, all the enumerated options and data range limits for each option?
In OpenBSD: all that is there. A documentation bug is a bug.
In Linux: "best wishes, and perhaps you'd like to write the man page for this utility you use once every two years?"
Disclosure: I use linux (through sheer inertia). I started on FreeBSD though, and got used to having adequate documentation.
I'm most efficient when I'm 1) in service to someone and 2) prioritizing their needs.
This applies to pretty much any interaction with people - but especially to personal relationships like family and parenting.
If the code branches the documentation branches, if it merges the documentation merges. Documentation can then made to be part of "code complete" for developers. Think README.md
However, there's always resistance to this wacky idea. Chief being the lack of tools and management fear of editing text files. This article also adds searchability to the negatives.
Start with the actions the reader needs to take (be at point x at time y wearing z) and then go in to specifics and reasoning.
Every time, I then go back and move that concluding sentence to the top. That way, the email starts with what I would like to happen, and if the recipient doesn't have any objections, the remainder of the email can be skipped entirely.
(Unless it's a novel, but then the goal is to build up a story to an apotheosis)
In US schoolsg english classes teach writing as an inverted pyramid where you give details (pyramid base) and end with a conclusion (pyramid point). In contrast, technical writing and journalism teach an inverted pyramid where you start with the conclusion (point) and fill out the details (base).
Think of The Atlantic long form articles contrasted with traditional newspaper frontpage stories. The Atlantic is telling a story to build context before getting to what you wait. A newspaper article tells you who was murdered with what and where and then builds up more context.
I really don't think this would stand up in court. Does anyone know of any concerts cancelled due to minor issues with the rider?
> The next week I sat down to meet with Caroline for the first time, and she couldn't have been more different than the previous writer. As soon as I began to explain the first routine, she started bombarding me with questions. She didn't mind admitting it when she didn't understand something, and she wouldn't stop badgering me until she comprehended every nuance. She began to ask me questions that I didn't know the answers to, like what happened when certain parameters were invalid. I had to keep the source code open on the screen of my Lisa when I met with her, so I could figure out the answers to her questions while she was there.
> Pretty soon, I figured out that if Caroline had trouble understanding something, it probably meant that the design was flawed. On a number of occasions, I told her to come back tomorrow after she asked a penetrating question, and revised the API to fix the flaw that she had pointed out. I began to imagine her questions when I was coding something new, which made me work harder to get things clearer before I went over them with her.
https://www.folklore.org/StoryView.py?story=Inside_Macintosh...
When I write documentation. I'm often at a point where I ask myself: do I document this small inconsistency/inconvenience, or do I just remove/fix it?
Often enough it's easier to make things more consistent than both documenting the inconsistency and getting people to read the docs and stop asking about it.
I had done the firmware for a piece of hardware that had some DIP switches to configure. I was having trouble doing the documentation for what each switch did and when you would want to configure it a particular way. Finally I realized it was because the switches weren't laid out logically, so I wrote the documentation the way I thought it should work then changed the code to match the documentation. Win-win, easier documentation and easier to use hardware.
So I end up writing the end-user documentation, then build a specification from there (functional requirements), then work on the technical design while prototyping various elements. Stringing together the prototypes often then ends up in a finished product.
I think what people miss most in the “mainstream” narrative is honesty & truth.
Clickbait all the documentation! ;-)
I still hold PHP documentation as a golden standard even though I haven't used the language in like 10 years. Everything is spelled out, and what's still unclear, there's usually a comment or two at the bottom of the page asking to clarify just that.
Contrast that with Python, my current main language... not only is it badly organized as a whole (where do I find documentation for `str`? Surely there's a page... no! it's all bundled up together in "Built-in types!"), the individual pages _also_ have no sensible structure and not even a good TOC! Python's jumping between versions and deliberate refusal to back-port features doesn't help either, but that's a different topic...
https://en.m.wikipedia.org/wiki/Goldfish#Cognitive_abilities
Of course, you should probably have more canaries.
(If it does, then it seems like the lack of that information is itself information.)
Sounds like there was little to no organization then.
I showed this to my co-worker who managed the technical aspects of a large college theater that also served the town. They hosted multiple large events including bands who had fleets of semi trailers to haul their gear. They had a single contract review person who read everything carefully and then coordinated the teams doling out requirements. As each team satisfied the requirements they would report back.
It's only to act as a canary, kind of a checksum (and I suspect it's not the only one, only the most obvious/curious).
When the band arrives into the venue, they check for canaries: if they see something wrong, it's a good enough reason to trigger a full inspection for serious issues.
However, as noted by others, this is rather moot: someone who didn't notice this line in the contract probably didn't notice all the other (more serious!) issues.
Why not? Under what legal doctrine?
Van Halen, at the time, were doing the largest stadium stage show ever. Most tours were 2 semi-trucks of speakers and lighting, VH were ~10+. Due to the never before done scale of the show rigging weight limits are critical. Not following it could lead to a stage collapse.
VH put the brown M&M’s in the middle of the weight requirement rider. This way the production crew could easily see if the local producer actually read the rider by seeing a bowl of brown M&M’s.
I also don’t really buy the explanation that brown candy would indicate that the facilities weren’t structurally/electrically safe. I think it’s more likely that the band were just a bunch of spoiled jerks.
I would fully expect a blue status LED to be an unambiguous 0000FF blue. If it was a soft baby blue, I would probably not have recognized it.
Most documentation definitely needs more attention towards organization.
But in my experience, organization is extremely difficult, especially because a documentation author may think of the system very differently than a new user might
The problem is that it requires a fair bit of documentation, coordination and processes to make it work, which some festivals do fine and I guess some just don't.
The key is that your head QA person knows who is in charge of what and has a process for holding them accountable, one such way would be to create a checklist of all the items that need to be checked, based on the riders, production requirements, regulations, expected amenities, plussing, etc.
Its also needed for each stage of the process, planning with stuff like speaker modeling, truss engineering, power load calculations, network and communication requirements, etc... on to checking the event area after load in and setup is complete and continuous checks on key items for safety and a reliable performance.
So, its certainly possible to reach an optimized state where you have a negotiated list of requirements and implement them correctly.
Advertizement above the NEXT button which keeps shifting while the page loads
Little did you know that the driver is actually
You have reached your free limit of 1 article per month, SUBSCRIBE HERE, but the button shifts again and now you have porn and "you have a virus" popping out everywhere
And you want to leave but the back button id hijacked and you understand why the etymology of vi is an Aztec phrase for "how do I get out of this shit"
If you are contracting in a situation like this a reasonable rate could mean $250-$1000 an hour. Really depends on what kind of money your currently make.
A better approach in the case would be to offer to investigate, and provide a flat rate. You can charge $3000 flat fee, and you may solve it in 1.5 hrs.
They accepted :(.
These guys were working with thousands of amps of electricity, hundred of pounds of equipment, pyrotechnics,etc. Could easily severely harm or kill someone if it wasn't setup properly. No obligation to do a show of the other side of the contract isn't being fulfilled
I blame the manager who came from a sales background. His response to every problem was to "call someone", rather than have the team work out what was wrong.
I picked up the phone, said my name, and as soon as they dropped that, I said "Oh, he's dead" and hung up. My former boss sent me a text later going "Very mature, but very funny"
Edit: Boss was the only one who had his head on straight
Pedantically proving instructions wrong (e.g. with a stopwatch and colorimeter) is a great way to submit a useful bug report with solid steps to reproduce, and a lot of the time it ends up solving the problem as well.
My suspicion is that it works fine with 5 actual clock seconds (instead of "a short while"), and that they just said 20 so that even the most chronologically challenged would end up holding it for at least 5.
As for containers, I’m not sure I follow. We ended up using vagrant and then test kitchen for our VMs, which really helped with on boarding. The team had too many people who couldn’t be expected to troubleshoot much of the backend anyways. We had stayed away from containerization because it added complexity without any clear benefits for our use cases. But test kitchen definitely papered over the need to get a local environment running with all the dependencies, which might change with different services, and that seemed like a good thing.
1. Nobody has to install dependencies. Docker is the only dependency (with compose).
2. Everybody has the same configuration.
3. Software versions are (mostly) tightly controlled. This requires whoever sets up the dev environment to make sure they use specific versions, and not :latest.
4. Devs don't need to spend time worrying about how the dev environment works, just the code.
This means that my README for a project usually has a section describing setup that just says:
1. run `dev/install` (any libraries from eg. NPM, go modules, etc.)
2. run `docker-compose up`
3. Check that the application is running on port XX.
This actually works great, and it does allow new devs to get to work quickly, and it does allow us to use devs that know very little about the underlying software that we're using, unless something doesn't work correctly. And that does happen, much more often than I would like. Then it takes my time and theirs to get up and running, and that was definitely not the goal.
That way the wiki stays up to date. Most corporate documents/wikis are worthless after a few years because things change but the wiki didn't. You need to constantly update it.
> after a bit of an ear bashing
If someone from my old employer calls and asks me politely for a bit of help with something I know well, I'd help.
If they call to yell at me about how I left behind a fragile system or how I left them in the lurch by quitting, the correct response is to tell them to get fucked, if they then ask for help after that, the correct response is to tell them to go fuck themselves.
Normalising that kind of abusive behaviour is not going to improve the lives of the co-workers you left behind.
You could warn him in advance about an impending negative issue. You could use lights, fireworks and even shout in his ears, but he would ignore you.
The the issue would occur and cause problems, big problems.
He would then ask "Why didn't you warn me?"
I would pull out my paper trail of emails, meeting notes etc.
To which he would reply "You didn't try hard enough to get my attention."
And that is why you don't put a career salesman in charge of your IT department.
“This is exactly the sort of behavior that made me leave. Do not contact me again. If you need something from me, have Steve call me instead.”
Let the people who actually gave a shit about you be your point of contact, not baby Napoleon.
Then you have angry baby Napoleon directing Steve to communicate with you and nobody wins.
If they call and ask they are in complete, dangerous illegality (I had once an American company czll me about an ex employee and they could not understand that).
Some companies used to ask for references, they were referred to friends and they do not ask anymore (this is a general case).
I had one of those for about a year and leaving after just over a year was a question I got used to answering.
The kind of person to lay into you like this is not going to give you a glowing reference whatever you do.
Spending 10 minutes on the phone to answer questions is one thing, as long as they are respectful, but more than that means that they want you to work for them.
Often, if made redundant by a company, you cannot return to work for them (as employee or contractor) for a year, otherwise you have to pay back your redundancy pay.
That leads to a potentially hilarious conversation about rates.
"I'll do it, my rates are 100 per hour plus 10K if you want me to start before June next year"
Anything that takes more than an hour should be billed. If the guys at the company are really your friends, they would fight to see you get paid.
This is a cliche but it can't possibly be true. I mean, it is extremely expensive to file a lawsuit, you probably lose, and nobody will ever hire you again, because it is public record.
That being said, the issue with redundancy packages is that taxes are involved and those guys will be inflexible if they find out that your package turns out not to be tax-free after all.