Brown M&Ms, or Why No One Reads the Manual

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.<p>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.<p>Three months later my phone starts ringing. I was in a new job so I didn&#x27;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&#x27;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.<p>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&#x27;t read the docs. They responded &quot;what docs?&quot;. 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.<p>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.

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.<p>Same principle as rubber duck debugging.

&gt; 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.<p>Common myth, but actually not true. Joe Rogan has 3 hour long talks with people and is one of the most popular media figures.<p>The <i>real</i> truth is, most information sucks (it&#x27;s both useless and boring), so people tune out. Improve information, get more attention.

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&amp;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&amp;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

I&#x27;m cable guy. If you are working on data center, there is chance we already met.<p>I&#x27;ve crimped so many RJ45. Can&#x27;t count.<p>Before CAT6 it was simple. After CAT6, all vendors starting produce their own.<p>This is my best manual all time. I love Penduit manual.<p><a href="http:&#x2F;&#x2F;www1.panduit.com&#x2F;heiler&#x2F;InstallInstructions&#x2F;N-COPN295--RevK--ENG.pdf" rel="nofollow">http:&#x2F;&#x2F;www1.panduit.com&#x2F;heiler&#x2F;InstallInstructions&#x2F;N-COPN295...</a>

No one reads the manual as a conclusion is belied by the use of brown M&amp;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.<p>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.

I don&#x27;t think much of this article. The Brown M&amp;M example seems a bit convoluted and anyway &quot;what to do instead&quot; is just a bunch of platitutes. &quot;Write doc to make it searchable&quot; ... ¯\_(ツ)_&#x2F;¯<p>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.<p>What the business calls a &quot;refresh&quot; of System X123 could be any of &quot;full copy from prod of the whole X123 data&quot;, &quot;can we please just import the subset of data I created in X123 Test?&quot;, &quot;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&quot;?<p>This happens (albeit less severely ... &quot;usually&quot;) 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 &quot;correct&quot; name is already used for something else in different context (e.g.: &quot;Sale prices&quot; - is it now? future? historical? only for agents? only for a specific country&#x2F;market...?).<p>Even just having a single, unambiguous lexicon would help a lot (and would make the &quot;searchabilitly&quot; a bit less mythical) but I don&#x27;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.

&gt; Properly reading the docs can take hours, and most don&#x27;t have that much time to spare.<p>And, reading the docs looks to an external observer exactly like playing video games or browsing facebook all day. Modern &quot;agile&quot; organizations dedicate two or three watchers to each actually productive employee to &quot;make sure&quot; 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.<p>That this necessarily produces a substandard product seems to be unimportant.

I haven&#x27;t read manuals ever, but last month I bought bluetooth headphones so to pair them I first tried without reading, and failed.<p>I opened the manual to find it was many pages of legal text and just one phrase of instructions: &quot;hold button for 5 seconds until light is blue&quot; and that failed too.<p>I mailed support and the instructions then came back as &quot;hold for 20 seconds, until light first becomes white, then blue&quot;, I simply mistaked the white led as very light blue.<p>This is why people don&#x27;t read manuals!

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

I write documentation for myself, because my brain is broken and I can&#x27;t remember anything. Also big Polaroid fan.

At my old job I used to flip my lid whenever I got a ticket (from QA) without logs.<p>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.

This is an ad.

I love this story.<p>At the same time I also thing its a little overly complicated.<p>Used to be an (amateur) sound tech &amp; realised pretty fast that stage stuff is an industry where its incredibly easy to tell who is on the ball and who isn&#x27;t.<p>I find it very hard to believe that an experienced band can&#x27;t just stroll across the stage with a can of beer &amp; know the answer 20 seconds later. No M&amp;M contracts needed.<p>Still cool story with a good message though

<a href="https:&#x2F;&#x2F;news.ycombinator.com&#x2F;item?id=7754334" rel="nofollow">https:&#x2F;&#x2F;news.ycombinator.com&#x2F;item?id=7754334</a>

I miss good `man` pages.

I&#x27;m tired of advertisements posing as blog posts. Can Hacker News include a notice on posts like these?

The article confirms a couple of principles that survived largely intact from my youth.<p>I&#x27;m most efficient when I&#x27;m 1) in service to someone and 2) prioritizing their needs.<p>This applies to pretty much any interaction with people - but especially to personal relationships like family and parenting.

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&#x27;t like being a human encyclopedia.

Just replying to the headline, but the people don&#x27;t read the manual because software is now intuitive enough that they don&#x27;t have to.

As a developer I&#x27;m a fan of checking the documentation into the same source code repo alongside the code.<p>If the code branches the documentation branches, if it merges the documentation merges. Documentation can then made to be part of &quot;code complete&quot; for developers. Think README.md<p>However, there&#x27;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.

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.

I always read manuals and they are pretty often crap.

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

&gt; If any brown M&amp;Ms were found backstage, the band could cancel the entire concert at the full expense of the promoter.<p>I really don&#x27;t think this would stand up in court. Does anyone know of any concerts cancelled due to minor issues with the rider?