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

111–120 of 153 posts

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

#111

Post by DoubleGlazing »

paiute wrote: post #89
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.

I was one of the few devs who actually did a README file. It contained all the headline gotchas and links to the wiki.

Few people took any notice of it.

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

#112

Post by michaelcampbell »

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…

> Rather than apologise they berated me ...

That nonsense would last exactly as much time as it took me to recognize the words and to hit "end call". The phone is for my convenience, not theirs.

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

#113

Post by DoubleGlazing »

SilasX wrote: post #95
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…

> Then they started calling my wife as she was listed as my next of kin. Minor tangent, but that got me to wonder: would that be legal under the GDPR, which only allows you to use data for the (legitimate) purpose it was collected for? In this case, they gathered next-of-kin info for (I assume) disbursal of benefits when the employee is dead or incapacitated. “To find the employee after he quits” would be out of that…

This was in 2013, pre-GDPR but in 1998 DPA territory. Yes, I do feel it was probably a DPA violation even back then.

In Ireland next of kin is purely for cases where the person has been incapacitated/hurt and someone needs to be told. Nothing to do with dispersal of benefits etc. There's a separate process for all that.

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

#114

Post by ghaff »

frobozz wrote: post #106
ghaff wrote: post #53

Earlier quoted context omitted.

Even if they're being a bit unreasonable, the momentary satisfaction of telling them to F Off is probably not worth the risk of it coming back to bite you some day.

If you don't want to tell them to F Off for this reason, you can contact their line manager, HR or customer service department and ask them to do it for you. The kind of person to lay into you like this is not going to give you a glowing reference whatever you do.

That is probably true. What I meant is that I would simply break off the conversation at that point. And, yes, if they kept pursuing it, I would either contact their manager if I had a good relationship or have HR tell them to knock it off.

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

#115

Post by cardiffspaceman »

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! ;-)

OP should have sent an email titled, "One weird fact about the DB driver!"

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

#116

Post by SilasX »

DoubleGlazing wrote: post #113
SilasX wrote: post #95

Earlier quoted context omitted.

> Then they started calling my wife as she was listed as my next of kin. Minor tangent, but that got me to wonder: would that be legal under the GDPR, which only allows you to use data for the (legitimate) purpose it was collected for? In this case, they gathered next-of-kin info for (I assume) disbursal of benefits when the employee is dead or incapacitated. “To find the employee after he quits” would be out of that…

This was in 2013, pre-GDPR but in 1998 DPA territory. Yes, I do feel it was probably a DPA violation even back then. In Ireland next of kin is purely for cases where the person has been incapacitated/hurt and someone needs to be told. Nothing to do with dispersal of benefits etc. There's a separate process for all that.

Sorry, yes, I forgot to include informing them of a workplace injury. And I assume GDPR wasn't in force there and then, just thinking of it as a hypothetical.

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

#117

Post by jkoudys »

conception wrote: post #76
swinnipeg wrote: post #74

Earlier quoted context omitted.

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.

Oh god yes. Otherwise it's always the same: try to bargain you down to billing 30 minutes work, then complaining that you didn't do the 1.5h of work they'd agreed wouldn't be done to save costs. The usual "in lieu of paying you more, we'll complain harder" nonsense every client from hell pulls.

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

#118

Post by koala_man »

bullen wrote: post #57

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

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.

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

#119

Post by DoubleGlazing »

trey-jones wrote: post #83
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 loca…

I am a proponent of the lowest common denominator model of development. Basically this means that whatever you develop should be understandable by a relatively new or junior developer. You should develop in such away that a someone coming in off the street should be able to pick up where you left off with minimal effort. This is partly about code, but also docs. Think about the next guy/gal. Is your code clean and well commented? But do you also have docs explaining the bigger picture? Think about what sort of documentation would have helped you get up to speed with the project. If people have to use compile errors to figure out what needs to be done to get up and running then you could have done better.
Post reply on HN