News for hackers. Stuff that matters.
Re:Brown M&Ms, or Why No One Reads the Manual by DoubleGlazing on Thursday July 30, 2020 @04:59AM (#23996034)
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 the apps I worked on.

Three months later my phone starts ringing. I was in a new job so I didn't answer, but they kept ringing. Then they started calling my wife as she was listed as my next of kin. My wife also didn't answer as she was with a client. After a few hours, my wife picks up the call and texts me that my previous employer was desperate to speak to me. So I called them during break and after a bit of an ear bashing I was informed their whole warehouse system was down and all business had stopped.

After a bit of diagnosis I realised that they had fallen for the first gotcha I listed in my docs, they deployed the wrong DB driver. I asked why they didn't read the docs. They responded "what docs?". I explained that I sent an email round before I left with guidance on the app. Rather than apologise they berated me for not doing more to alert people to the existence of the information. It was that attitude that contributed to me wanting to leave the company in the first place.

I think the moral is that no matter how good your docs, some people will always ignore them even when the world is collapsing around them.

Re:Brown M&Ms, or Why No One Reads the Manual by ed312 on Thursday July 30, 2020 @07:42AM (#23996974)
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.
Re:Brown M&Ms, or Why No One Reads the Manual by jkoudys on Thursday July 30, 2020 @09:50AM (#23998078)
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.
Re:Brown M&Ms, or Why No One Reads the Manual by swinnipeg on Thursday July 30, 2020 @10:13AM (#23998391)
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 by conception on Thursday July 30, 2020 @10:16AM (#23998431)
And -always- minimum two hours.
Re:Brown M&Ms, or Why No One Reads the Manual by jkoudys on Thursday July 30, 2020 @12:40PM (#24000209)
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 by PopeDotNinja on Thursday July 30, 2020 @01:30PM (#24000809)
Or just set a day rate, and limit scope to helping with the specific problem. "It's $1200/day, and scope is limited to helping you understand how to recover from the described problem. All of the work recovery work will be done by you, and my role will be limited to advising."
Re:Brown M&Ms, or Why No One Reads the Manual by xyzzy_plugh on Thursday July 30, 2020 @09:54AM (#23998128)
I agree, but I'd say your missing a zero.
Re:Brown M&Ms, or Why No One Reads the Manual by redisman on Thursday July 30, 2020 @10:58AM (#23998945)
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 by jacquesm on Thursday July 30, 2020 @04:05PM (#24002323)
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 by learnstats2 on Thursday July 30, 2020 @05:35PM (#24003113)
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 by wheelerwj on Thursday July 30, 2020 @05:14AM (#23996101)
> 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.

Re:Brown M&Ms, or Why No One Reads the Manual by jedberg on Thursday July 30, 2020 @05:33AM (#23996197)
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.

Re:Brown M&Ms, or Why No One Reads the Manual by frobozz on Thursday July 30, 2020 @09:33AM (#23997892)
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 themselves.

Normalising that kind of abusive behaviour is not going to improve the lives of the co-workers you left behind.

Re:Brown M&Ms, or Why No One Reads the Manual by DoubleGlazing on Thursday July 30, 2020 @11:46AM (#23999511)
My ex-manager was the reason I left. He was.... odd.

You could warn him in advance about an impending negative issue. You could use lights, fireworks and even shout in his ears, but he would ignore you.

The the issue would occur and cause problems, big problems.

He would then ask "Why didn't you warn me?"

I would pull out my paper trail of emails, meeting notes etc.

To which he would reply "You didn't try hard enough to get my attention."

And that is why you don't put a career salesman in charge of your IT department.

Re:Brown M&Ms, or Why No One Reads the Manual by hinkley on Thursday July 30, 2020 @11:16AM (#23999141)
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.

Re:Brown M&Ms, or Why No One Reads the Manual by learnstats2 on Thursday July 30, 2020 @05:39PM (#24003148)
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 by learnstats2 on Thursday July 30, 2020 @06:34AM (#23996550)
Alternatively: Help your co-workers and friends by normalising getting paid for real work outside of what is contracted.
Re:Brown M&Ms, or Why No One Reads the Manual by DoubleGlazing on Thursday July 30, 2020 @05:39AM (#23996236)
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.
Re:Brown M&Ms, or Why No One Reads the Manual by BrandoElFollito on Friday July 31, 2020 @02:54AM (#24006332)
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 by brightball on Thursday July 30, 2020 @11:48AM (#23999551)
If you run into one of those where you don't have a choice, the best phrasing I've found to explain why I left was "hostile work environment."

I had one of those for about a year and leaving after just over a year was a question I got used to answering.

Re:Brown M&Ms, or Why No One Reads the Manual by citiguy on Thursday July 30, 2020 @12:21PM (#23999945)
Most people won't give a bad personal reference anymore because they are too afraid of being sued. We just say yes, the person worked here from this time to that time.
Re:Brown M&Ms, or Why No One Reads the Manual by perl4ever on Saturday August 01, 2020 @12:17AM (#24017542)
>because they are too afraid of being sued

This is a cliche but it can't possibly be true. I mean, it is extremely expensive to file a lawsuit, you probably lose, and nobody will ever hire you again, because it is public record.

Re:Brown M&Ms, or Why No One Reads the Manual by ghaff on Thursday July 30, 2020 @08:24AM (#23997262)
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.
Re:Brown M&Ms, or Why No One Reads the Manual by frobozz on Thursday July 30, 2020 @12:18PM (#23999909)
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.

Re:Brown M&Ms, or Why No One Reads the Manual by ghaff on Thursday July 30, 2020 @12:35PM (#24000139)
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 by mytailorisrich on Thursday July 30, 2020 @06:02AM (#23996358)
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.

Re:Brown M&Ms, or Why No One Reads the Manual by ghaff on Thursday July 30, 2020 @08:23AM (#23997256)
I agree although in some circumstances, contracting for your former employer may be violating your employment agreement with your current one.
Re:Brown M&Ms, or Why No One Reads the Manual by mytailorisrich on Thursday July 30, 2020 @08:41AM (#23997399)
That does not mean that you should do it for free (which might still be a contractual breach, btw).
Re:Brown M&Ms, or Why No One Reads the Manual by ghaff on Thursday July 30, 2020 @08:49AM (#23997474)
Theoretically maybe. In practice, no one to a first approximation is going to have an issue with you spending an hour helping a prior employer with some cleanup related to your prior job. Employment agreements tend to use words like outside employment/consulting/etc. They don't (and it would probably be unenforceable if they did) generally forbid you from talking to a former employer.
Re:Brown M&Ms, or Why No One Reads the Manual by frobozz on Thursday July 30, 2020 @05:06PM (#24002839)
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"

Re:Brown M&Ms, or Why No One Reads the Manual by mytailorisrich on Thursday July 30, 2020 @05:43PM (#24003187)
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 by true_religion on Thursday July 30, 2020 @09:34AM (#23997919)
I don’t think it’s rude to give them your rates.... but then again I have been only working with consultancies for the past 15+ years, so even in house work gets a billable rate attached to it.

Anything that takes more than an hour should be billed. If the guys at the company are really your friends, they would fight to see you get paid.

Re:Brown M&Ms, or Why No One Reads the Manual by DoubleGlazing on Thursday July 30, 2020 @05:29AM (#23996164)
That's what my wife told me as soon as I got home. If it ever happens again that's what I'll do.
Re:Brown M&Ms, or Why No One Reads the Manual by WrtCdEvrydy on Thursday July 30, 2020 @05:35AM (#23996204)
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

Re:Brown M&Ms, or Why No One Reads the Manual by wincy on Thursday July 30, 2020 @10:23AM (#23998507)
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 by WrtCdEvrydy on Thursday July 30, 2020 @10:37AM (#23998684)
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 by mrpotato on Thursday July 30, 2020 @09:43AM (#23998005)
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).
Re:Brown M&Ms, or Why No One Reads the Manual by MrLeap on Thursday July 30, 2020 @10:30AM (#23998590)
I use a statement of work template.
Re:Brown M&Ms, or Why No One Reads the Manual by Wistar on Thursday July 30, 2020 @12:26PM (#24000017)
Yes! In my experience a well-crafted SOW is key to the practical understanding between client and contractor. Good SOW language is clearer and, IMO, psychologically less daunting to negotiate than contract language. The SOW provides a roadmap not just for the project but for the writing of the actual contract.
Re:Brown M&Ms, or Why No One Reads the Manual by brightball on Thursday July 30, 2020 @11:46AM (#23999506)
Exactly.

When people treat you that way, you politely say "If you want my help, change your tone."

If they don't, hang up.

Re:Brown M&Ms, or Why No One Reads the Manual by nix23 on Thursday July 30, 2020 @07:39AM (#23996955)
Wow, that is exactly my Story, up to the jdbc driver!!

That was the first time they called.

I made a perfect confluence-wiki, for every server a page, for every application on that server a sub-page.

The Code-repo-links the config's the howto's everything was in there, the second time about 2 month after i went for the other job, they floded a Oracle-Db, called me and asked really rude what a shit installation i made, so i asked for the server pointed them to the Wiki-site and the first sentence boldly written said: DEV-VM -> DB-scheme-migration (DONT put DATAS IN, 20GB-DISK)

Re:Brown M&Ms, or Why No One Reads the Manual by DoubleGlazing on Thursday July 30, 2020 @07:57AM (#23997062)
In this case the server app had multiple DLLs imported from other projects and they had been compiled against a specific version of the Oracle .net driver.

My docs clearly stated that you should not update the driver unless you were willing to rebuild all the other projects as well. I could only deploy one copy of the driver file, so it had to be the version all the different parts of the application were expecting. It was an old app, whoever started development on it didn't know about repositories and DB singletons - there were DB connections all over the place.

The annoying thing is that the .net error message they were getting actually stated what the problem was in fairly clear terms, yet they still called me.

Re:Brown M&Ms, or Why No One Reads the Manual by trey-jones on Thursday July 30, 2020 @10:38AM (#23998691)
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 by eire1130 on Thursday July 30, 2020 @11:44AM (#23999486)
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 clear understanding of how all the garments are stitched together.

Re:Brown M&Ms, or Why No One Reads the Manual by milesvp on Thursday July 30, 2020 @12:20PM (#23999932)
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 up using vagrant and then test kitchen for our VMs, which really helped with on boarding. The team had too many people who couldn’t be expected to troubleshoot much of the backend anyways. We had stayed away from containerization because it added complexity without any clear benefits for our use cases. But test kitchen definitely papered over the need to get a local environment running with all the dependencies, which might change with different services, and that seemed like a good thing.

Re:Brown M&Ms, or Why No One Reads the Manual by trey-jones on Friday July 31, 2020 @09:55AM (#24008584)
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.

Re:Brown M&Ms, or Why No One Reads the Manual by bluGill on Thursday July 30, 2020 @12:54PM (#24000372)
When I'm asked a question I often respond it is on the wiki. If it isn't on the wiki it is your job to put it there. If it is wrong and you know why fix it. If it is wrong and you fail to figure out why, then talk to me, but I won't respond except to say I fixed the wiki.

That way the wiki stays up to date. Most corporate documents/wikis are worthless after a few years because things change but the wiki didn't. You need to constantly update it.

Re:Brown M&Ms, or Why No One Reads the Manual by DoubleGlazing on Thursday July 30, 2020 @12:44PM (#24000261)
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.
Re:Brown M&Ms, or Why No One Reads the Manual by paiute on Thursday July 30, 2020 @11:03AM (#23998996)
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 by DoubleGlazing on Thursday July 30, 2020 @12:29PM (#24000073)
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 by michaelcampbell on Thursday July 30, 2020 @12:30PM (#24000089)
> 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 by SilasX on Thursday July 30, 2020 @11:42AM (#23999458)
> 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 scope, then, right?

Re:Brown M&Ms, or Why No One Reads the Manual by DoubleGlazing on Thursday July 30, 2020 @12:34PM (#24000131)
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 by SilasX on Thursday July 30, 2020 @12:39PM (#24000198)
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 by DoubleGlazing on Thursday July 30, 2020 @12:51PM (#24000345)
The 1998 DPA was still pretty strict. I have no doubt the DPA was violated when they called my wife.

I blame the manager who came from a sales background. His response to every problem was to "call someone", rather than have the team work out what was wrong.

Re:Brown M&Ms, or Why No One Reads the Manual by rndgermandude on Thursday July 30, 2020 @12:17PM (#23999896)
I manage the "support" (mostly DMCA) tickets for some small website we run as a hobby project without monetization whatsoever (aka "for fun"). People are free to use it, e.g for chat and to share content (i.e. DMCA magnet). It's maybe like 5-20 such tickets per day, most of which are DMCA and can be handled really quick, so it isn't that much of a time drag.

Not actually getting paid/having an employer there can be quite liberating...

Since nobody who ever writes me is a customer, and I am not getting paid anyway, I am more or less free in what level of politeness I apply. I usually try to model my response after the initial requests I receive - taking into account other factors like people who might be genuinely upset; or confuse me with the person who actually uploaded a piece of content.

We have users from all over the world, and it's rather interesting to see particular patterns/attitudes with certain types of locales.

For example, Americans - by and large - are too lazy to read the few lines of text on our contact page detailing what information we need to address what kind of problem, and often are rather rude from the get-go, and really like to threaten with their lawyers (plural!) in the initial email when it comes to copyright or related issues. This then leads to me asking for the missing details, followed by a lot of them demanding to talk to my supervisor, to which I then point out that they are not our customers and that being rude or even outright insulting the only person who could potentially help them (for free) isn't maybe the best idea they ever had... And if the supervisor demand came up, I point out that I do not have a supervisor, I demand to talk to their supervisor instead.

It would be unfair to only unload on Americans, tho. We got a lot of Portuguese users, and tickets from the Portuguese are even more rude on average and of course nobody bothers to read the instructions, tho nobody ever demands to talk to my supervisor. The French are polite but like to make outrageous demands, but seem to read the instructions. Germans are "professional"-polite but tend to write LOOONG emails, and when it comes to copyrights usually cite a lot of completely unrelated laws, but again read the instructions. Middle/South Americans are usually polite but constantly think the Subject line is where all their text is supposed to go, and do not read the instructions. I'd say the most pleasant people are the East European (mostly Polish and Russian) people who write me... I don't remember anybody outright rude from East Europe ever, tho the language barrier - our website is English only incl the instructions - is often rather obvious (but I will not fault anybody for that, of course).

Point being: the level of RTFM in my limited experience differs quite a bit depending on locale.