
Brown M&Ms, or Why No One Reads the Manual - zzaner
https://blog.nuclino.com/brown-m-ms-or-why-no-one-s-reading-the-manual
======
DoubleGlazing
A few years ago I left the company I was was working for. We had an internal
doc wiki that hardly anyone used. I was one of the ones who did and I would
document code changes and things like how to setup a dev environment and to
list known gotchas.

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.

~~~
wheelerwj
> after a bit of an ear bashing

you actually helped them? Hang up, charge your emergency hour consultant
rates, and tell them you're available once they sign the agreement.

~~~
jedberg
I would help. The people who are suffering the most are your former coworkers.
Presumably friends. Definitely people you may work with in the future.

I'd rather be known as the guy who helps than the guy who is rude about
consulting rates.

~~~
DoubleGlazing
That would cross my mind. Most potential employers I've encountered have
usually asked for references from my last two jobs. On another occasion I had
to undergo a background check which involved contacting my last 15 years worth
of employers. So no matter how much I may have disliked an employer I would be
unwilling to burn bridges until I knew I would never need to rely on them
again.

~~~
brightball
If you run into one of those where you don't have a choice, the best phrasing
I've found to explain why I left was "hostile work environment."

I had one of those for about a year and leaving after just over a year was a
question I got used to answering.

~~~
citiguy
Most people won't give a bad personal reference anymore because they are too
afraid of being sued. We just say yes, the person worked here from this time
to that time.

~~~
perl4ever
>because they are too afraid of being sued

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_.

------
bowjack-deerman
An often overlooked benefit of writing documentation (regardless of whether
anyone will read it) is that it forces you to explain everything in a
structured way and discover things that can be improved or simplified.

Same principle as rubber duck debugging.

~~~
perlgeek
I totally agree.

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.

~~~
mark-r
I remember well one time long ago when I did that.

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.

------
tomp
> We are impatient and have a shorter attention span than a goldfish. To be
> properly absorbed, information needs to be organized in a way that
> accommodates that.

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.

~~~
redisman
Joe Rogan is very light listening though. I doubt people actually sit in their
armchair listening intently for 3 hours without doing anything else. People
also love to binge watch TV - does that mean there’s no attention span issues?

~~~
tomp
Not sure about that... I’m just listening the Weinstein episodes (first Bret,
not Eric). they’re talking about very controversial topics and going very deep
- mainstream media would dismiss most of those as just “conspiracy theories”
without even considering them rationally on their merits. I might be biased
though, maybe those epispdes aren’t as popular as some other guests.

I think what people miss most in the “mainstream” narrative is honesty &
truth.

------
greatpatton
This is quite strange, having organized a large music festival this kind of
document were split among different teams. Meaning that people in charge of
the backstage are managing their part (getting food, M&Ms, specific brand of
beer, and other non nonsensical request, etc) and the people in charge of the
stage and technical stuff are taking care of technical requirements (and
aligning them between different bands sharing the same stage). So if someone
from the backstage team messed up the M&Ms, it will bring absolutely no
information about how the situation was handled by the guys in charge of the
stage... So this canary will be quite ineffective in reality

~~~
MisterTea
> So if someone from the backstage team messed up the M&Ms, it will bring
> absolutely no information about how the situation was handled by the guys in
> charge of the stage...

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.

~~~
greatpatton
This may be possible for a theater hosting a unique event, but never for a
music festival, where you have like 30-50 different artists/bands on one
night. There you have people responsible for each aspect. Of course you have a
stage manager responsible for the overall operation of each stage, but there
is no way that a guy can make sure that everything is ok in all details for
all artists (the riders sheets can sometime several pages of different
requests, like that hotel room must contains this kind of pillow etc.). As you
say you have to delegate, and if one of the guys of the backstage team forget
to sort the M&Ms, it will be a problem for the guy in charge of the backstage,
but that's it. Like in any large organization, you cannot imply that because
the customer support guy messed up that all the engineering team is bad. So
here, if they wanted to make sure that technical guideline where followed it
would be better to put something like: please mark all this kind of cable with
pink and yellow tape.

~~~
kayfox
In my experience doing video work for some of these type events, its possible
for a music festival to negotiate riders that work for the festival an
implement them properly, it might take a few more people and decent planning
ahead of time.

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.

------
dontdieych
I'm cable guy. If you are working on data center, there is chance we already
met.

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...](http://www1.panduit.com/heiler/InstallInstructions/N-COPN295
--RevK--ENG.pdf)

~~~
kozak
And for all the perfectionists out there, this perfect manual has a typo in
figure 9 at page 2.

~~~
jagged-chisel
Nah, that's fine - you just have to read it with the correct accent

------
bryanrasmussen
No one reads the manual as a conclusion is belied by the use of brown M&Ms as
a canary - if no one read the manual then it would not be useful to have a
canary because no one would read it and then everyone would have to check
stuff to make sure it worked before performing themselves and there be an
extra charge to venues for this check.

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.

~~~
sixhobbits
No one reads manuals (unless they're written using our documentation tool) is
the point here.

~~~
bryanrasmussen
Van Halen anecdote predating tool also shoots that point down though, but I
guess the deeper point about Van Halen is at any rate people got to make
money, so I guess I should forgive Nuclino the rhetorical bombast.

------
Pamar
I don't think much of this article. The Brown M&M example seems a bit
convoluted and anyway "what to do instead" is just a bunch of platitutes.
"Write doc to make it searchable" ... ¯\\_(ツ)_/¯

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.

~~~
yjftsjthsd-h
I once had the joy of working for a company that had rebranded its own
products, sometimes multiple times, and was inconsistent about which name
would call things by. Oh, and several products had similar names and would be
abbreviated to the same thing. Helpdesk spent an insane amount of time just
finding out what product any given ticket was actually for; they had a
document that tried to to list all products and all the names that each
product was known by and who a point of contact was for each product, but it
was incomplete and didn't necessarily have enough information disambiguate
many cases.

~~~
Pamar
Well, yes - this is a somewhat extreme case but the problem is the same even
for internal-use-only corporate systems. And it becomes even more acute when
(as it is my case) your first language is not the same originally used to
develop the first version of the system.

(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).

------
commandlinefan
> Properly reading the docs can take hours, and most don't have that much time
> to spare.

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.

~~~
doorstar
I just faced this - I was trying to write a somewhat complex MongoDB query and
I decided it was finally time to read a book rather than just cutting-and-
pasting from stack overflow until I stumbled across something that seemed to
work.

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.

~~~
grimjack00
You read the book; you're now the expert.

------
bullen
I haven't read manuals ever, but last month I bought bluetooth headphones so
to pair them I first tried without reading, and failed.

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!

~~~
koala_man
This has also been my experience writing documentation.

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.

~~~
perl4ever
You don't know the difference between white and blue for sure until you've
seen both. I actually recently had more or less this problem trying to set up
my cable modem (maybe it was something like is it blinking, pulsing, or
flickering, but anyway).

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.

~~~
koala_man
>You don't know the difference between white and blue for sure until you've
seen both

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.

------
quotha
Actually, a lot of people read, most of the time there were no brown M&Ms and
the stage was set up correctly.

------
turbinerneiter
I write documentation for myself, because my brain is broken and I can't
remember anything. Also big Polaroid fan.

------
gpmcadam
This is an ad.

------
Havoc
I love this story.

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

------
gwbas1c
At my old job I used to flip my lid whenever I got a ticket (from QA) without
logs.

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.

------
jacquesm
[https://news.ycombinator.com/item?id=7754334](https://news.ycombinator.com/item?id=7754334)

~~~
dang
If curious see also

2018
[https://news.ycombinator.com/item?id=18643258](https://news.ycombinator.com/item?id=18643258)

2011
[https://news.ycombinator.com/item?id=2839581](https://news.ycombinator.com/item?id=2839581)

2009
[https://news.ycombinator.com/item?id=743860](https://news.ycombinator.com/item?id=743860)

------
pmlnr
I miss good `man` pages.

~~~
tuatoru
Me, too.

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.

~~~
skibbityboop
The worst thing you can see in a Linux manpage: "For complete explanations,
see the info(5) documentation"

------
mitchdoogle
I'm tired of advertisements posing as blog posts. Can Hacker News include a
notice on posts like these?

------
WarOnPrivacy
The article confirms a couple of principles that survived largely intact from
my youth.

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.

------
annoyingnoob
I always write the docs. I point to the docs when I get questions. Most people
skim over the once and then just ask questions later when they forget. I don't
like being a human encyclopedia.

------
im3w1l
Just replying to the headline, but the people don't read the manual because
software is now intuitive enough that they don't have to.

~~~
commandlinefan
Except for the software that isn't. Which is the only software that reasonable
knowledge of is valuable.

------
RegW
As a developer I'm a fan of checking the documentation into the same source
code repo alongside the code.

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.

------
dpc_pw
Another tip: when writing communication (like email), start with TL;DR.
Explain quickly who should read it and why. Start with the important stuff
first, follow up with details and less important stuff.

~~~
erikbye
Good writing avoids Internet memes and Reddit speak.

~~~
solarkraft
Nice writing includes cultural elements.

------
watwut
I always read manuals and they are pretty often crap.

------
mothsonasloth
I thought it was Ozzy Osbourne who required 1000 brown M&Ms in a brandy glass?
:)

------
barbegal
> If any brown M&Ms were found backstage, the band could cancel the entire
> concert at the full expense of the promoter.

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?

~~~
cjhveal
The brown M&M's were supposedly a canary that prompted a line-by-line check of
the technical specifications of the production for errors, which would then be
the grounds to cancel the show. Snopes has a good article[0] on the Van Halen
rider.

[0]: [https://www.snopes.com/fact-check/brown-
out/](https://www.snopes.com/fact-check/brown-out/)

~~~
barbegal
I understand its purpose as a canary. I'm just questioning the idea of
"cancelling the entire concert at the full expense of the promoter" which
seems false.

~~~
huffmsa
Likely they wouldn't, but if during their line chrck, they found other more
dangerous omissions and failures by the promotor to setup the stage and
equipment correctly, they definitely could cancel.

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

