9 ms·

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 documen

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.

wheelerwj 6y ago
> 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.
- DoubleGlazing 6y ago
  That's what my wife told me as soon as I got home. If it ever happens again that's what I'll do.
  - WrtCdEvrydy 6y ago
    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
    - wincy 6y ago
      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.
      - WrtCdEvrydy 6y ago
        That's a good point, but these guys just wanted me to help them unfuck what they fucked up.
- jedberg 6y ago
  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.
  - DoubleGlazing 6y ago
    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.
    - ghaff 6y ago
      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.
      - frobozz 6y ago
        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.
        ghaff 6y ago
        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.
    - brightball 6y ago
      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.
- mrpotato 6y ago
  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).
  - MrLeap 6y ago
    I use a statement of work template.
    - Wistar 6y ago
      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.
- brightball 6y ago
  Exactly. When people treat you that way, you politely say "If you want my help, change your tone." If they don't, hang up.
nix23 6y ago
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)
- DoubleGlazing 6y ago
  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.
ed312 6y ago
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.
- jkoudys 6y ago
  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.
  - xyzzy_plugh 6y ago
    I agree, but I'd say your missing a zero.
  - swinnipeg 6y ago
    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.
    - conception 6y ago
      And -always- minimum two hours.
      - jkoudys 6y ago
        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.
  - PopeDotNinja 6y ago
    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."
Bobbcatt 6y ago
Should have asked them for 5k/hour consultant fee. You have them by the balls, with their entire warehouse system down, and you don't work for them anymore.
trey-jones 6y ago
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.
- eire1130 6y ago
  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.
  - milesvp 6y ago
    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.
paiute 6y ago
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.
- DoubleGlazing 6y ago
  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.
SilasX 6y ago
> 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?
- DoubleGlazing 6y ago
  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.
  - SilasX 6y ago
    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.
    - DoubleGlazing 6y ago
      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.
rndgermandude 6y ago
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.
michaelcampbell 6y ago
> 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.

wheelerwj 6y ago

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

DoubleGlazing 6y ago
That's what my wife told me as soon as I got home. If it ever happens again that's what I'll do.
- WrtCdEvrydy 6y ago
  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
  - wincy 6y ago
    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.
    - WrtCdEvrydy 6y ago
      That's a good point, but these guys just wanted me to help them unfuck what they fucked up.
jedberg 6y ago
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.
- DoubleGlazing 6y ago
  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.
  - ghaff 6y ago
    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.
    - frobozz 6y ago
      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.
      - ghaff 6y ago
        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.
  - brightball 6y ago
    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.
mrpotato 6y ago
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).
- MrLeap 6y ago
  I use a statement of work template.
  - Wistar 6y ago
    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.
brightball 6y ago
Exactly. When people treat you that way, you politely say "If you want my help, change your tone." If they don't, hang up.

nix23 6y ago

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)

DoubleGlazing 6y ago
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.

ed312 6y ago

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.

jkoudys 6y ago
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.
- xyzzy_plugh 6y ago
  I agree, but I'd say your missing a zero.
- swinnipeg 6y ago
  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.
  - conception 6y ago
    And -always- minimum two hours.
    - jkoudys 6y ago
      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.
- PopeDotNinja 6y ago
  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."

Bobbcatt 6y ago

Should have asked them for 5k/hour consultant fee. You have them by the balls, with their entire warehouse system down, and you don't work for them anymore.

trey-jones 6y ago

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.

eire1130 6y ago
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.
- milesvp 6y ago
  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.

paiute 6y ago

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.

DoubleGlazing 6y ago
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.

SilasX 6y ago

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

DoubleGlazing 6y ago
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.
- SilasX 6y ago
  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.
  - DoubleGlazing 6y ago
    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.

rndgermandude 6y ago

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.

michaelcampbell 6y ago

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