Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

blog.nuclino.com

Post reply on HN
Print view View original

81–90 of 153 posts

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

#81

Post by rsa25519 »

tomp wrote: post #75
high_5 wrote: post #66

Earlier quoted context omitted.

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

> I'm not so sure... just, like, maybe put one single thought into organizing 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

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

#82

Post by WrtCdEvrydy »

wincy wrote: post #77
WrtCdEvrydy wrote: post #36

Earlier quoted context omitted.

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.

That's a good point, but these guys just wanted me to help them unfuck what they fucked up.

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

#83

Post by trey-jones »

DoubleGlazing wrote: post #30

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…

A good story, and I find myself in a similar position (the one who writes the docs). I think a lot about this topic, because as our company grows it becomes more and more important, and more and more difficult to impart all of the scattered knowledge on new hires.

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.

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

#84

Post by m463 »

ChrisMarshallNY wrote: post #18
m463 wrote: post #3

Earlier quoted context omitted.

Sounds similar to teaching a subject, or making a presentation about it. You will be forced to learn it very thoroughly yourself. "best way to learn something is to teach it to someone else".

I have found that the best way to create perfect software, is to teach it to someone.

Teaching someone about perfect software can only be done in lisp, grasshopper. :)

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

#85

Post by redisman »

ed312 wrote: post #49
DoubleGlazing wrote: post #30

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…

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

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

#86

Post by redisman »

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?

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

#88

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

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

#89

Post by paiute »

DoubleGlazing wrote: post #30

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…

But why are your instructions in the back closet when they could be taped directly to the code in the readme or in the comments and error messages? I've had similar phone calls, to which I respond "it's all in the README." Never heard from them again.

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

#90

Post by commandlinefan »

im3w1l wrote: post #87

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.

Except for the software that isn't. Which is the only software that reasonable knowledge of is valuable.
Post reply on HN