How Would You Document Your Job?

Q3vi1 asks: "As an support technician, there are several things I've learned about the environment I work in that would be difficult to find out without hours of research. Now I'm going to be moving and that means getting a new job. Before I do, I'd like to leave behind some of this information for the person who will replace me. How does one document all the details in an efficient manner for the next tech?"

Instructions for My Replacement

[ahknight]

Good for you! You've got yourself a wonderful job as my replacement. As a congratulations gift I would like to leave you with the knowledge I've gleaned from my time here.

Imagine the best possible place you could work. Imagine people working together, sharing information in a timely manner, and open to constructive criticism. People working together to not only make a profit, but make a humane profit. People who care about the customer, each other, and the world in general. People who feel that the workload should be spread over all nations so that everyone can have a job, an income, and a healthy life.

Now imagine the reverse. Welcome to the team, sucka'!

why?

[Anonymous Coward]

why would you want to do this? are they paying you a bonus if you do this? is it in your contract? is the new guy a friend of yours?

just curious. I would just up and leave and let them figure it out (but I usually keep good ongoing documentation so I'm not really being as much of a dick as it sounds).

but it is a good question, why do something you don't have to do, especially when it comes to business?

Quirks

[Kris_J]

I've prepared a 'quirks' document of everything (IT) unique to the company that you couldn't get from a reference book. If someone new needs anything more, they shouldn't have been hired.

Reinforce the point I was going to make

[OldMiner]

But he's leaving now. Any "up-to-date" is already gone.

The best way to have valuable knowledge is to gather it continuously and write it down in a consistent format. This way you both have documentation for your successor when you leave with advanced notice, and when you leave due to the 26 Speed Bus to Downtown doesn't notice you crossing the intersection. Not to rag on the good intentions of the original poster of this article, but isn't this a little late to start documenting?

Perhaps leaving a consistent documentation system to start from might be one of the most valuable assets he can leave the company -- for the gal after the guy after him.

Don't document your job

[spooky_nerd]

How about not documenting your job? Then when your replacement finds out he can't do what you did you can get hired back as a consultant for triple the pay.

Cookbook of job recipes

[StarWynd]

First, write everything down. Don't worry about organization at this point. Just get all of your thoughts down before you forget them. Next, determine the two or three keywords that categorize each tip and use those for the organizing things. Remember that things will fall into multiple categories. Use these categorizations to build up a comprehesive index into you tips. And there you have it.

The most important thing to remember is that you're writing this for someone else coming along, so tips need to be short and to the point and easily locatable. Basically, you're writing an O'Reilly "Cookbook" [atomz.com] style document for your job.

Riiiiiiiiiight

[SmallFurryCreature]

Well very nice of you but in practice there only a few kinds of documentation.

• The perfect documentation, it details exactly the requirements and how this were met. It list the business logic used and the algorithms with detailed examples. It explains the architecture of the product and on wich others it relies and in what form. It list who is responsible for what and who takes over if a person should be unavailable. It lists contacts at suppliers and even alternate suppliers. It in short tells you every thing you need to know.

  Small detail. You will only ever find this kinda of documentation for obsolete projects. Nothing current will have this. Ever.

• The non documentation. There isn't any. This is perhaps the best as at least it saves reading it. Unlike the next one.
• This is kinda like the first one except it isn't relevant. This kinda is like those japananese->english->dutch VCR manuals that you finally figure out are for a different version or in extreme cases a different product.
• But last is the worst one. The extremely detailed but entirely useless one. The documentation that lists in details all the step neccassry to say turn on the pc but totally fails to mention any error codes or problem solving steps. You know the ones. Move mouse to the left button->click left mouse button by pressing down lightly with finger etc etc etc. But completly fail to mention what error-code 21 means.

Personally I try to avoid writing documentation nowadays. In my line of work (webdevelopment) there isn't any time/budget to write documentation let alone keep it uptodate. I generally find it more usefull to tell a new person the internal details of the company then the details of the code. If they are any good they can figure out the code. Figuring out a new company is a lot harder.

For the guy I am going to replace, please document who is responsible for what, who actually takes responsibilty, who is the suckup, who is the guy/gal actually making the decisions and how much of a nutcase the boss is. Your code I can always rewrite.

Too late.

[jotaeleemeese]

That is the first step, not the last, during a job cycle.

Do it properly in your next job and start documenting as soon as you put your fat behinf in your new chair.

DO whatever you can for the position you are leaving, most likely you will be caught doing many other things, so documentation most likely will be lacking any way.

Re:Hello Communism.

[Glonoinha]

Wow, you are the first person to perfectly articulate that not only is the current situation (re: outsourcing) in America fucked up, it is even more fucked up than Communism.
Good job, honestly.

OP: There is a saying in coding about documenting your code - 'If it was hard to write, it should be hard to read.' It is a joke, mostly, but it offers insight into your situation.

You didn't pick up everything in your job in a week by reading over someone else's notes (or you would be leaving those notes behind.) I'm guessing you have been there a while and probably invented half the stuff in your shop (procedures, protocols, naming conventions, etc.) so none of it is going to be in a book. There is just some stuff you 'just gotta know', meaning it can't be learned by the normal knowledge gleaning methods, you just gotta know (above which ceiling tiles are the switches, for example.)

The good news is that he (your replacement) doesn't have to do it 'your way' - he just has to get it done ... and there are as many different ways to do infrastructure as there are sys/admins.

Your company is about to learn that keeping all their tech eggs in one basket (having only one guy) is a bad idea. Even a part timer college kid to shadow you as an intern for $7.50 / hour would have been quite the safety net. Do what you can, but there is no way to safely insure the ongoing performance of all your systems in two weeks - hell it takes a week just for the new guy to figure out how the building is layed out, who is who, and what is what. After that, come up with a way to provide emergency support and price is slightly prohibitively to keep them from abusing it. Take your old hourly rate, times 1.3 and that's what they paid you 40 hours a week to be there, that's your baseline. Twice that per hour, with half an hour as the minimum charge, for all contact / questions leaves them with an emergency way to keep running and gives you a little money to keep your interest piqued.