I'm on my way out of a company doing tech work for an SMB (Small or Medium-sized Business) and I happen to be the only expert on various parts of the company's operation. I gained this knowledge through a combination of school, training and experience.

My boss has now asked me to write a step-by-step guide to do much of the maintenance work that comes up on a daily basis, presumably so he can pass off the responsibilities to some poor help desk technician or other employee who has no idea how to do any of it. These are things that really should be done by someone who is qualified, because not only are they complicated (and potentially dangerous if not done right) but there are whole career fields based on doing exactly this.

It is clear he does not plan to hire someone to replace me in these tasks, and I have already warned him multiple times that it's a bad idea to try to cut corners like this or just hope it works out, but to no avail.

I'm not really okay with burning bridges despite the fact that I may never need them again.

Am I obligated to write the guide on "How to do my job" or is this asking something unreasonable? Keep in mind we're not talking about simple fixes or notes, we're referring to entire maintenance and update routines for software that is being hosted for clients.

  • 13
    Are you okay with burning bridges and not being eligible for rehire at this company? You should include that in the question, as it could impact the answers.
    – jmort253
    Commented Sep 17, 2014 at 21:17
  • 12
    related: How can I prepare for getting hit by a bus?
    – gnat
    Commented Sep 18, 2014 at 13:12
  • @ChrisLively and thanby, I agree, the general idea is burning bridges is not okay. We three are all on the same page here, but I'm asking not for me but to make sure we get the best possible answers here, answers that don't make false assumptions about your goals. Hope this helps clarify. As an aside, I edited your comment into the post.
    – jmort253
    Commented Sep 20, 2014 at 21:54

7 Answers 7


While you are still employed with this company, you are obligated to fulfill the responsibilities of the position. If your boss tells you that he wants you to write this guide, then you should do it to the best of your ability. You have already advised him that he needs someone trained to do the job, and it's his decision whether he wants to listen to your advice or not. You will be leaving soon, at which point it won't be your problem to worry about anymore!

Pulling in some good advice from the comments:

It's worth noting anything in your guide that is particularly "high risk" should specifically state so. To an untrained person this is almost a game of mine sweeper. (only with their reputation and possibly job on the line) It's not their fault your boss effectively set them up to fail, but you can improve their odds by at least saying. "You see this setting here? yeah that one... Never Set it to daily... If you do the server will max it's hard drive over night, before utterly failing leaving you to try and restore a backup costing the company hundreds of thousands of dollars.... Good luck!" - RualStorge

In those places that you think require a highly trained expert, just write "this job should be left to an expert trained in X, Y and Z". Or "if X happens, find a trained expert". - gnasher729

  • 18
    @RualStorge: even worse is when the system under consideration is fundamentally unruly, so that it's not practicable to list all the gotchas of that kind. Basically there's a reason that a brain surgeon can't just write a "how to do my job" guide and hand it to a minimum-wage hire off the street, and part (admittedly not all) of that reason is dealing sensibly with the myriad of things that can go wrong in ways subtly different from all the ways it has ever gone wrong before. Commented Sep 18, 2014 at 1:01
  • 4
    Is step one going to be spend 3 years at uni, training courses, etc? Its a shame to see this getting voted up so much when for most technical roles it should be impossible to summarise into simple steps. Documentation of your specific implementation should ideally have been done as you go, a handoff is only realistic to someone with base skills in the technologies you have used. While you may have to do what you are asked, if the task is undoable it is just as much your responsibility to highlight that.
    – JamesRyan
    Commented Sep 18, 2014 at 9:37
  • 29
    @SteveJessop brain surgeons definitely do write up "how to do my job" guides and the exact procedures that should be followed in certain manipulations - documenting best practice, results from experience, likely pitfalls, and also an ordered [check]list for all the trivial things that must not be forgotten. It doesn't mean that I can do brain surgery by reading the documentation; but it will be very helpful for a skilled brain surgeon that is doing that particular procedure for the first time (that's how new procedures spread around the world), and the exact same thing can be done in IT.
    – Peteris
    Commented Sep 18, 2014 at 13:21
  • 1
    @JamesRyan You can write guides for even the most technical things in maintenance mode, and so long as things work as they should the guide will hold true. (that's what the OP should write) how to respond when things don't go as planned, well that's where a degree is necessary. (Case and point you can teach anyone to maintain an established water filtration system back flowing filters when X happens, Adding Y chemical when water shows a reading of Z, etc.) But when the water gets contaminated or a system fails... That's when the poorly trained person is utterly screwed. Commented Sep 18, 2014 at 13:57
  • 1
    @RualStorge IT systems are about managing change. It is extremely rare that anything can be just maintained as is for very long.
    – JamesRyan
    Commented Sep 18, 2014 at 14:02

Sounds like your company has some real key-man risks. You should definitely do as requested. Document, document, document.

Start with an outline of the main topics you should cover, and bounce it off your boss.

Then create an outline of each topic. Don't worry about complete sentences when you're listing items, just get the basic ideas and steps down. Do this in the order of importance (most important stuff first!)

Did you finish? Still working there? Go over it with your boss and/or your replacements (let's hope they have some overlap with your tenure so you can hand-off smoothly). Find out what's not clear to them, and write it up in more detail and with greater clarity. Explain the things you thought were obvious but that they didn't get.

Review your main outline, did you forget anything? Add it in. Is there a particularly confusing subject that they just seem to not grasp? Write it up a different way.

Done? Back it up in several places, and print out a few hard-copies to store in separate locations, and ask to take it with you for future reference. I see big consulting fees in your future if they choke on this.

  • 4
    "Take it with you for future reference" can be illegal. Leave the documentation with your employer, along with your contact details. If they do call you for consulting, they should have the documentation waiting for you. Commented Sep 18, 2014 at 7:17
  • 12
    @StephanKolassa Which is why he wrote "ask to take it with you"...
    – Alexander
    Commented Sep 18, 2014 at 10:17
  • 2
    Agreed. Knowledge in someone's head is not safe — whether or not that person still works there. One accident and you've lost the knowledge! It is more than fair for an employer to require that knowledge be entered in some sort of knowledgebase. However, it is also fair for the KB to be audience-relevant. If procedure X needs a qualified engineer, then write the KB such that it won't be useful to someone without the qualification, as well as stating "This procedure needs this qualification". Commented Sep 19, 2014 at 3:19
  • @GreenstoneWalker It'd be more like "don't deliberately write the KB such that someone without the qualification can use it, if doing so compromises the ability of someone with the qualification can use it effectively". There is no need to deliberately make things more complicated than they need to be. There is a lot of need to be specific enough that someone who knows what they are doing can perform the procedure correctly.
    – user
    Commented Sep 19, 2014 at 9:33
  • Case in point, if I write a guide on how to set up a development environment for a product, I'm going to assume familiarity with the development tools (so in the case of e.g. Visual Studio might write "go to Team Explorer and click the X toolbar button" or "open config.xml and set root/config/path to the source code root path"), but that just means that someone not familiar with the development tools will have to do a lot more looking around to find the parts they need in order to follow the guide. Quite often, that can be enough, iff that's agreed upon as a good outcome of writing the guide.
    – user
    Commented Sep 19, 2014 at 9:36

It is quite normal to do this kind of stuff when one has announced their departure. Just put in the time and be as nice about it as you can. No need to work long hours.

It really isn't your problem how they are going to find a qualified person to do the job. It could very well be that your job vacacny is some help-desk technician's big break. The best opportunities come to people who are, at least on paper, woefully under-qualified.

That said, some activities are probably better documented with a 10 minute screencast than a wall of text. If you want to be super nice about it, ask around for exactly what people want documented.

  • 2
    @Myles: Creating a video archive of how to outsource you, and implicitly assigning copyright to your soon-to-be-ex-employer, unless this was agreed to be one of your job tasks, is seriously nuts (what if the employer turns around and resells or licenses that video?). The OP would do better to negotiate some ongoing training or support rate after they leave, on an hourly rate basis, and subject to availability.
    – smci
    Commented Sep 18, 2014 at 0:47
  • 7
    @smci This is a standard part of many people's jobs.
    – jwg
    Commented Sep 18, 2014 at 10:36
  • 1
    @jwg: it's not a standard part of most people's jobs. Everything can be negotiated for. Reducing your market value for no consideration is nuts. Training a replacement is one thing, creating a permanent video of how to replace you then assigning it without royalty or restriction to someone else is wack. Again: what if the employer turns around and resells or licenses that video?
    – smci
    Commented Sep 18, 2014 at 19:19
  • 5
    Just like the employer turns around and sells the software I wrote while they were paying me? Nothing. If you want to move up, obsolete your current position. If your current employer doesn't have anywhere up for you to go, you've made yourself more valuable to the next employer. Commented Sep 18, 2014 at 22:30
  • @smci, this appears to be just operational stuff specific to the company-- hardly "sellable". Screen-casts are sometimes easier and less tedious than prose to show how something is done.
    – teego1967
    Commented Sep 19, 2014 at 18:43

Exits are often a relief but the last months or weeks can be emotional, even stressful. Writing a step-by-step guide isn't easy - especially if writing is not your usual way of communicating. I assume you are leaving for a better opportunity and that your current boss needs a schematic to use when things break. My advice is to do your best to knock out a list of best-practice fixes to common problems and don't obsess about whether it a perfect solution. The boss will make future adjustments on the fly as needed. Your obligation is to peck away until time to go and remain clear sighted about the big picture.

  • 1
    The Asker seemed to think the boss wasn't capable.
    – Aaron Hall
    Commented Sep 18, 2014 at 4:14
  • 2
    @AaronHall: then the boss will still make future adjustments on the fly, but they'll be wrong and that won't be the questioner's fault... Commented Sep 18, 2014 at 4:16
  • I don't think this one deserved the down-votes, it's pretty level-headed advice.
    – thanby
    Commented Sep 18, 2014 at 15:11

I can understand your reasoning to a point. To me the analogy is replacing a chef with a cook who uses the chef's recipes. The food may not be quite as good and this person is probably not going to be able enhance the menu and keep up with the latest trends. The cook may not be able to handle the exceptions like a really busy night or being able to substitute for a missing ingredient.

They're taking a risk. Things may work out or they won't. A lot of this will depend on how you write the instructions. Is it just a list of do this, then that or will you include screen shots, and detailed explanations. Example: If this happens, reboot the server, is just fine if the person knows and has experience with it.

What's the worse thing that can happen? They eventually hire someone who knows what they're doing?

  • 2
    That's a pretty good analogy, but I think it would be more like replacing a chef with a dishwasher (considering it would be done by someone who isn't even in the same field). The chef's recipes would have to include things like "How to turn on the cooktop," and "How to chop vegetables with a knife," not just "Cook these ingredients in this order at this temperature." They are indeed taking a risk, and I guess I'm also wondering if I'm going to get in trouble if my instructions aren't good enough for the dishwasher.
    – thanby
    Commented Sep 18, 2014 at 15:39
  • I've had the luxury of writing instructions and then silently looking over someone's shoulder while they try it out. Then I have an idea of what needs to be corrected or added. If the person just doesn't get it, they may be more persuasive (panicky) in recommending hiring someone who knows what they're doing.
    – user8365
    Commented Sep 18, 2014 at 17:31
  • @thanby, How do turn on the cooker should be in the recipes, as each cooker is different. Chopping veg should not be, unless the veg is chopped in a special way.
    – Ian
    Commented Sep 20, 2014 at 12:02

While your job is to do what your boss tells you, it is also your duty to perform your tasks state-of-the-art. So writing a HowTo should include who it is intended for, what qualifications the person needs, where he or she needs deeper understanding and why, and what potential risks come with the tasks if they are not done correctly.

If you do not do it this explicit, you run into legal problems as soon as your replacement causes any damage. Theoretically you should also keep a copy of the documents you create as proof, but if you are allowed to do this is another legal matter that you should discuss with a lawyer. Just like the question if and how you should write the documentation should be discussed with a lawyer.

A bonus: If you mention to your boss that you talked to your lawyer and that you will write it exactly like this, he can hardly argue with that. ;)

Important: All discussions you had with your boss are useless and never happened, write him mails, make him answer in writing and keep copies.

  • 6
    In which country can someone have legal consequences in such case? Sounds crazy Commented Sep 18, 2014 at 7:25
  • 4
    +1 for the first paragraph. Documentation is key for IT roles but it always assume a certain level of competence on the part of the person reading it. Writing this kind of technical documentation for a layman would be on par with writing several textbooks.
    – Lilienthal
    Commented Sep 18, 2014 at 10:21
  • 5
    Warning about 'legal problems' == complete nonsense.
    – jwg
    Commented Sep 18, 2014 at 10:35
  • 1
    Unsubstantiated legal claims that 'legal problems' == complete nonsense are complete nonsense. Even if jwg was a practicing attorney in the relevant jurisdiction he doesn't have your employment contract so is, at best, stating how he thinks intellectual property ought work; ignore it.
    – msw
    Commented Sep 18, 2014 at 13:12
  • @msw: "Intellectual Property" is entirely irrelevant. There are no legal problems, because the employment contract has ended, and the hypothetical problem discussed did not exist during the period of employment. The exact contract text is irrelevant for something that is not covered at all by the contract. (And on a hypothetical, you'd just blame it on your predecessor)
    – MSalters
    Commented Oct 20, 2017 at 13:02

If you have gained this knowledge overtime from the work then it is very reasonable for your boss to ask you to write up a guide of how to do it so that others don't have to relearn what you did. Just think how much time it would have saved you if you had some of those instructions written out for you when you started. It isn't about cutting corners by getting someone less trained to do it but not having to relearn how to do things again and make the same mistakes again.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .