Live data from Hacker News

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

blog.nuclino.com

141–150 of 153 posts

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

#141

Earlier quoted context omitted.

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

Hahah I actually like to decide my rate on this exact basis - what amount of money would I feel happy if they accepted.

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

#142
post #92
post #64

Earlier quoted context omitted.

You missed this bit: > after a bit of an ear bashing If someone from my old employer calls and asks me politely for a bit of help with something I know well, I'd help. If they call to yell at me about how I left behind a fragile system or how I left them in the lurch by quitting, the correct response is to tell them to get fucked, if they then ask for help after that, the correct response is to tell them to go fuck t…

Better compromise: “This is exactly the sort of behavior that made me leave. Do not contact me again. If you need something from me, have Steve call me instead.” Let the people who actually gave a shit about you be your point of contact, not baby Napoleon.

What benefit is there in saying this to baby Napoleon directly?

Then you have angry baby Napoleon directing Steve to communicate with you and nobody wins.

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

#143
post #52

Earlier quoted context omitted.

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"

If that's a contractual obligation between them and you they just need to waive it in writing so that you're protected.

That being said, the issue with redundancy packages is that taxes are involved and those guys will be inflexible if they find out that your package turns out not to be tax-free after all.

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

#144

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.

Rarely. For old hardware. Cross cable. One end is B other end is A

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

#145
post #38

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

And for all the perfectionists out there, this perfect manual has a typo in figure 9 at page 2.

The beauty is I even tried read. Just look figures then done.

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

#146

No one reads the manual as a conclusion is belied by the use of brown M&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. The fact that some people do not read makes a canary useful. I guess the title m…

Maybe the documentation equivalent would be to have a program halt early on and ask the user to perform an action detailed on X page of the manual, so the user would need to at least acknowledge the existence of the manual before getting anything done.

Not sure if that would just piss off users beyond toleration, but it's an interesting idea.

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

#147
post #35

Earlier quoted context omitted.

I would help. The people who are suffering the most are your former coworkers. Presumably friends. Definitely people you may work with in the future. I'd rather be known as the guy who helps than the guy who is rude about consulting rates.

That would cross my mind. Most potential employers I've encountered have usually asked for references from my last two jobs. On another occasion I had to undergo a background check which involved contacting my last 15 years worth of employers. So no matter how much I may have disliked an employer I would be unwilling to burn bridges until I knew I would never need to rely on them again.

This is why you cannot get anything more from your previous rmployerd than a certificate of work in France.

If they call and ask they are in complete, dangerous illegality (I had once an American company czll me about an ex employee and they could not understand that).

Some companies used to ask for references, they were referred to friends and they do not ask anymore (this is a general case).

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

#148
post #66

Earlier quoted context omitted.

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

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

And then proceed to a 37 pages long doc, where he explains the history of drivers since 1745, and repeats and repeats

Advertizement above the NEXT button which keeps shifting while the page loads

Little did you know that the driver is actually

You have reached your free limit of 1 article per month, SUBSCRIBE HERE, but the button shifts again and now you have porn and "you have a virus" popping out everywhere

And you want to leave but the back button id hijacked and you understand why the etymology of vi is an Aztec phrase for "how do I get out of this shit"

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

#149
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 al…

Well, yes - this is a somewhat extreme case but the problem is the same even for internal-use-only corporate systems. And it becomes even more acute when (as it is my case) your first language is not the same originally used to develop the first version of the system.

(Imagine an ERP system built in UK and adopted and customized by a French company, for example: IT would probably use 20% of French terms/names, the rest will be in English... Business will do the opposite).

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

#150

Earlier quoted context omitted.

I agree with both (1) and (2). We require all devs, as a part of the onboarding process to read, improve and correct the docs for onboarding for each new hire. A PR is required. This forces all developers to understand what happens when something actually breaks and also how to locate the information, should the need arise. This is also why we've never Dockerized. It masks too many issues and no one seems to have a c…

Very much this. New hires must always be tasked to improve onboarding documentation. At a previous place I worked, I went from expecting it to take a new hire several months to be productive to less than a couple weeks and a big reason was continuing to have newbies tweak docs and fill in details that might be easy to gloss over by soneone who already knows the tech. As for containers, I’m not sure I follow. We ended…

I can maybe give some idea of what he's saying about containers. We do use Docker, and when I mentioned in my original comment that I aimed to lower the skill required to come onto a project, Docker is the primary vehicle for that effort. Here are my reasons:

1. Nobody has to install dependencies. Docker is the only dependency (with compose).

2. Everybody has the same configuration.

3. Software versions are (mostly) tightly controlled. This requires whoever sets up the dev environment to make sure they use specific versions, and not :latest.

4. Devs don't need to spend time worrying about how the dev environment works, just the code.

This means that my README for a project usually has a section describing setup that just says:

1. run `dev/install` (any libraries from eg. NPM, go modules, etc.)

2. run `docker-compose up`

3. Check that the application is running on port XX.

This actually works great, and it does allow new devs to get to work quickly, and it does allow us to use devs that know very little about the underlying software that we're using, unless something doesn't work correctly. And that does happen, much more often than I would like. Then it takes my time and theirs to get up and running, and that was definitely not the goal.

Post reply on HN