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

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

#71

Post by cannabis_sam » Thu, Jul 30, 2020, 1:53 PM UTC

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…

Even the simile they used is based on incorrect information.

https://en.m.wikipedia.org/wiki/Goldfish#Cognitive_abilities

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

#72

Post by xyzzy_plugh » Thu, Jul 30, 2020, 1:54 PM UTC

jkoudys wrote: post #69

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 agree with all of that, except for making it a reasonable rate. Go up to the edge of reasonable, then bump it up by $15/h.

I agree, but I'd say your missing a zero.

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

#73

Post by Pamar » Thu, Jul 30, 2020, 2:05 PM UTC

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.

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

#74

Post by swinnipeg » Thu, Jul 30, 2020, 2:13 PM UTC

jkoudys wrote: post #69

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 agree with all of that, except for making it a reasonable rate. Go up to the edge of reasonable, then bump it up by $15/h.

Shoot higher!

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.

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

#75

Post by tomp » Thu, Jul 30, 2020, 2:16 PM UTC

high_5 wrote: post #66

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…

> Improve information, get more attention. Clickbait all the documentation! ;-)

I'm not so sure... just, like, maybe put one single thought into organizing it?

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

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

#76

Post by conception » Thu, Jul 30, 2020, 2:16 PM UTC

swinnipeg wrote: post #74

jkoudys wrote: post #69

Earlier quoted context omitted.

I agree with all of that, except for making it a reasonable rate. Go up to the edge of reasonable, then bump it up by $15/h.

Shoot higher! 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.

And -always- minimum two hours.

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

#77

Post by wincy » Thu, Jul 30, 2020, 2:23 PM UTC

WrtCdEvrydy wrote: post #36

DoubleGlazing wrote: post #33

Earlier quoted context omitted.

That's what my wife told me as soon as I got home. If it ever happens again that's what I'll do.

I've actually done worse to a bad employer... 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

I know a woman who did this but to credit collection agencies. One day the police showed up at work and arrested her for fraud. Obviously not the same thing as you had no contractual obligation to them, but telling everyone you’re dead is generally a bad practice.

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

#78

Post by MrLeap » Thu, Jul 30, 2020, 2:30 PM UTC

mrpotato wrote: post #68

wheelerwj wrote: post #31

Earlier quoted context omitted.

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

What would I bingle for if I was looking for a template for such an agreement/contract? It seems like the kind of thing you would want to have prepared in advance (in case of emergency, break glass).

I use a statement of work template.

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

#79

Post by MisterTea » Thu, Jul 30, 2020, 2:31 PM UTC

greatpatton wrote: post #32

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

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

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

#80

Post by derekp7 » Thu, Jul 30, 2020, 2:35 PM UTC

bowjack-deerman wrote: post #2

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.

This is similar to what I've found, in that writing documentation for a product before I've written any code actually makes the product turn out better. When in design / development mode, I tend to think of all kinds of "cool" features to put in, but since using them requires knowledge of my state of mind at the time I designed them, it gets very difficult to document these features.

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.