Brown M&Ms, or Why No One Reads the Manual • Hacker News Board

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

#131

Post by tomp » Thu, Jul 30, 2020, 6:06 PM UTC

redisman wrote: post #86

tomp wrote: post #58

> 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 attentio…

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?

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.

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

#132

Post by skibbityboop » Thu, Jul 30, 2020, 6:07 PM UTC

dontdieych wrote: post #5

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

Do you ever see places running T568A? I've never seen anything but B in 22 years of IT work.

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

#133

Post by koala_man » Thu, Jul 30, 2020, 6:14 PM UTC

bluGill wrote: post #124

koala_man wrote: post #118

Earlier quoted context omitted.

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.

I'm color blind so don't blame me. If it turns white then blue I can probably see that, but if it turns white and there is no warning it goes through white before blue I'll assume you just got a different led on the line.

It's fair to assume that the docs are simply wrong/outdated about the specific duration and color when it works, but I would start to question those assumptions when it doesn't.

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.

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

#134

Post by skibbityboop » Thu, Jul 30, 2020, 6:16 PM UTC

tuatoru wrote: post #20

pmlnr wrote: post #8

I miss good `man` pages.

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?" Disclosur…

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

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

#135

Post by bluGill » Thu, Jul 30, 2020, 6:31 PM UTC

koala_man wrote: post #133

bluGill wrote: post #124

Earlier quoted context omitted.

I'm color blind so don't blame me. If it turns white then blue I can probably see that, but if it turns white and there is no warning it goes through white before blue I'll assume you just got a different led on the line.

It's fair to assume that the docs are simply wrong/outdated about the specific duration and color when it works, but I would start to question those assumptions when it doesn't. 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.

20 seconds is long enough that I will not wait that long in general. When something else happens in 3 seconds that seems like it could be right I might wait 5 more seconds when it doesn't work, but not 20.

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

#136

Post by yjftsjthsd-h » Thu, Jul 30, 2020, 6:31 PM UTC

Pamar wrote: post #73

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 co…

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.

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

#137

Post by jacquesm » Thu, Jul 30, 2020, 8:05 PM UTC

redisman wrote: post #85

ed312 wrote: post #49

Earlier quoted context omitted.

First thing you do is email them a contract with a _reasonable_ consultant hourly rate. You literally handed them documentation in advance and they didn't bother to read or test it. Don't feel bad, don't get angry, get paid.

I would ask for 5x my rate easily in this case where I don’t want the work

I once desperately wanted to get out of a bunch of work that someone wanted me to do so I did what you suggested.

They accepted :(.

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

#138

Post by koala_man » Thu, Jul 30, 2020, 8:31 PM UTC

bluGill wrote: post #135

koala_man wrote: post #133

Earlier quoted context omitted.

It's fair to assume that the docs are simply wrong/outdated about the specific duration and color when it works, but I would start to question those assumptions when it doesn't. 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.

20 seconds is long enough that I will not wait that long in general. When something else happens in 3 seconds that seems like it could be right I might wait 5 more seconds when it doesn't work, but not 20.

Did it need all 20 seconds? If so, the docs were definitely wrong and useless and I see your point.

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.

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

#139

Post by Havoc » Thu, Jul 30, 2020, 8:57 PM UTC

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

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

#140

Post by frobozz » Thu, Jul 30, 2020, 9:06 PM UTC

ghaff wrote: post #52

mytailorisrich wrote: post #42

Earlier quoted context omitted.

Asking to be paid for work is not being rude. 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.

I agree although in some circumstances, contracting for your former employer may be violating your employment agreement with your current one.

In some circumstances, it may even be violating your termination agreement with the former one.

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"