Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

How Would You Document Your Job?

Cliff posted more than 10 years ago | from the leaving-behind-some-of-your-experience dept.

Communications 50

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

Sorry! There are no comments related to the filter you selected.

Three (4, Funny)

SpaceLifeForm (228190) | more than 10 years ago | (#9534903)


Re:Three (4, Informative)

baywulf (214371) | more than 10 years ago | (#9534990)

For those not familiar with the three envelope joke: The three envelopes []

Re:Three (1)

Micro$will (592938) | more than 10 years ago | (#9535477)

I've seen this joke in BSD Fortune, but it involved Stalin and Khrushchev, and instead of reorganize, it was a traitor purge.

Instructions for My Replacement (5, Insightful)

ahknight (128958) | more than 10 years ago | (#9534906)

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'!

Hello Communism. (1)

Scott Robinson (108176) | more than 10 years ago | (#9534946)

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.

What makes you think that if all the workload was spread evenly throughout all nations that everyone would have a job, an income, and a healthy life?

Anything at all backing that up?

Re:Hello Communism. (1)

ahknight (128958) | more than 10 years ago | (#9534965)

Not to nitpick, but communism does not feel that everyone in other nations deserves a job. :)

Moral capitalism (a new concept, I know) would argue that point. Anything to back it up? We've helped India tremendously so far. If others outsource to America, well, good for us all.

Re:Hello Communism. (3, Insightful)

Glonoinha (587375) | more than 10 years ago | (#9536738)

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.

Re:Hello Communism. (1)

jazman_777 (44742) | more than 10 years ago | (#9535144)

What makes you think that if all the workload was spread evenly throughout all nations that everyone would have a job, an income, and a healthy life?

It's not communism. The problem is that he cares more about people across the globe, whom he's never met, than his neighbors right here. Probably never met them, either, it's America...

Re:Hello Communism. (1)

PD (9577) | more than 10 years ago | (#9538385)

He did use the word 'imagine', no?

Write a manual... (1)

howman (170527) | more than 10 years ago | (#9534914)

and do it all in l33t...

Re:Write a manual... (3, Funny)

jayrtfm (148260) | more than 10 years ago | (#9535053)

or Hindi...

Re:Write a manual... (1)

BestNicksRTaken (582194) | more than 10 years ago | (#9574676)

Nah, your replacement would be able to read Hindi...

why? (1, Insightful)

Anonymous Coward | more than 10 years ago | (#9534916)

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?

Re:why? (1)

Mind Booster Noori (772408) | more than 10 years ago | (#9538631)

why would you want to do this?
Have you ever heard about work ethics?

Re:why? (0)

Anonymous Coward | more than 10 years ago | (#9539356)

Have you ever heard about work ethics?

I think my grandpa mentioned something about these...

WikiWikiWiki (4, Informative)

BortQ (468164) | more than 10 years ago | (#9534929)

The best thing for you to do is set up a Wiki. It will be very easy for you to write down your stuff. Whether in big chunks or in little "Oh, I should write down this little thing before I forget". And it will be easy for your successors to continue keeping the docs up-to-date.

Reinforce the point I was going to make (3, Insightful)

OldMiner (589872) | more than 10 years ago | (#9534968)

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.

Re:Reinforce the point I was going to make (0)

Anonymous Coward | more than 10 years ago | (#9535307)

The best solution is to move to the next job and let the next sucker figure it out for himself just like you did. Your employer isn't going to do you any favors when you move on, so why should you do any favors for them?

What is with people and their tendancies to kiss their employers asses? Wake up - you don't need to be a loyal company man anymore because copmanies are no longer loyal to employees. Don't waste your time.

Re:Reinforce the point I was going to make (1)

jtev (133871) | more than 10 years ago | (#9535467)

Um, what if the reason he's leaving the position is because he's getting a promotion within the company, or getting a better job somewhere else. If he's getting an internal promotion it'll look good on him that he went through the effort to minimize the business trauma of the transition. If he's going out of the company, still, no reason to fuck his employer over, and if he likes his coworkers he might see this as a way to help them. Just because he no longer has the position he is vacating doesn't mean it's not enlightened self interest to do this. Hell, the person replacing him may be a manager one day, and think to himself, well this fine fellow made my life easy for no gain to himself, and acted in a profetional manner, I should hire him for $highpayingjob because he did right by me before I even knew him.

Re:Reinforce the point I was going to make (1)

e7 (117450) | more than 10 years ago | (#9535699)

for the gal after the guy after him.
Remember: if the guy after him has a gal after him, then he is probably not a nerd, so he needs all the help he can get.

Re:Reinforce the point I was going to make (1)

ameoba (173803) | more than 10 years ago | (#9537856)

Exactly. Even if you can't fully populate the wiki, if you put enough stuff in there that the next guy will find it useful enough to keep putting info in, you've improved the system.

Re:WikiWikiWiki (-1, Offtopic)

Anonymous Coward | more than 10 years ago | (#9536031)

"What could make a print job spool at unusually slow rates to the printer?"

In my experience, glacially slow printing times can usually be traced back to a third-rate operating system. As you've no doubt discovered since installing Linux, printer hassles [] are among the countless inconveniences you must suffer if you insist on using an operating system with no polish, no professionalism and no sense of responsibility to the end user. I would suggest buying a Mac, or, at the very least, switching back to Windows XP.

Good luck.

Quirks (4, Insightful)

Kris_J (10111) | more than 10 years ago | (#9534945)

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.

And the real answer (4, Interesting)

ahknight (128958) | more than 10 years ago | (#9534952)

Having had this responsibility before, let me tell ya, it's easy.

Make a document with headings about each part of the company you know about (Departments, Management, Placing 1-900 Calls Unnoticed, etc.) and then, very simply, just talk about it. Such as:

Accounting tends to only make itself known when you need something critical and then they cry wolf. When this happens contact their manager, Foo B. Baz, and let him know what's happening. He'll kick someone's ass and get the PO through.
Sales lies. Repeatedly. If one of them calls you with the customer already on the line (and they will) and says something to the order of "we do X, right? Of course we do!" talk over him and explain why he's an idiot. With the customer there. It will be the last time that particular person calls you like that. Sales management will harass you, but just refer him to your manager and move on.

And so on, and so forth. Just a simple heading/topic document. Print it up and leave it in a drawer somewhere the next sucker will see it.

Just write it down (1)

booch (4157) | more than 10 years ago | (#9535160)

The first part is easy enough: just write down what you think a new person would need to know. The second part is hard: organizing all the information so that he can find it. Unfortunately, I don't have too much advice on how to go about organizing things.

Don't document your job (2, Insightful)

spooky_nerd (646914) | more than 10 years ago | (#9535184)

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.

The real answer (1)

Phexro (9814) | more than 10 years ago | (#9535187)

Don't document anything. It's called job security, you fool!

Simple really (2, Funny)

MerlynEmrys67 (583469) | more than 10 years ago | (#9535200)

1 Learn Hindi
2 ???
3 Profit

Cookbook of job recipes (2, Insightful)

StarWynd (751816) | more than 10 years ago | (#9535215)

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" [] style document for your job.

Good luck! (1)

ebrandsberg (75344) | more than 10 years ago | (#9535233)

I don't know what type of support position you are in, but I'm a sr. support technician at a networking company myself. If you are in such a position, the best thing is to spend what little time you have writing faq's for people, providing the best (but concice) description of how to do various tasks you do on a daily basis, and provide any documents you reference on a regular basis to those that will replace you. On the other hand, it would probably take as long as you have been working for the company to document everything you learned, so you have to be able to narrow it down to what is really important. Good luck on this task, and good luck on your new job!

Re:Good luck! (1)

ultranova (717540) | more than 10 years ago | (#9538180)

If you make written instructions on how to do your job, what's stopping your job from being outsourced to India ?

Never document anything. Always remember that the corporation just wants to make money out of you and doesn't care about you beyond that, so treat it in the same manner.

Re:Good luck! (1)

ebrandsberg (75344) | more than 10 years ago | (#9538345)

Why let your wife go outside the house, some other guy may decide to ask her out for a date. Why drive a car as you could be in an accident.

If you read the article you would realize he is leaving on good terms, and helping out as he leaves will help him get a good reference if he needs one later. There is no downside to him helping, and only a benifit if he does.

possibly (1)

dtfinch (661405) | more than 10 years ago | (#9535323)

Document everything out of the ordinary. Summarize the rest, the obvious. Assume they know or can quickly figure out the basics and tell them everything you expect to give them trouble. And attach your email address to the documentation.

Riiiiiiiiiight (2, Insightful)

SmallFurryCreature (593017) | more than 10 years ago | (#9535368)

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... (2, Informative)

cornice (9801) | more than 10 years ago | (#9535394)

After years of having to learn the same things over and over because I didn't document things as I did them I have come up with a plan that works well for me. The first thing is to document everything. For that I have a set of IMAP mail folders that contains notes that I wrote to myself. If I find something interesting or if I do something that I might do again I just mail myself a little note about it. It's IMAP so I have it anywhere I have an internet connection.

After that I have a wiki that is similar but a bit more organized. This is where I put the stuff that I know someone will be interested in. It's also where I create user docs and FAQs.

Finally I have some critical documents that I created with Scribus. This is the bible for my job. Anything that I have to have in an emergency goes in there.

Beyond that, I keep important code in CVS.

Since this is an afterthought at this point I would go straigt to the wiki and printed documentation.

Depends on what your goal is... (1)

cowbutt (21077) | more than 10 years ago | (#9535683)

If you want job security, follow this [] to the letter. If you want to do an ethical pass-the-baton job, invert all of that article's recommendations and do that instead. ;-)


Re:Depends on what your goal is... (0)

Anonymous Coward | more than 10 years ago | (#9537868)

Wow. That's incredibly fucking evil.

I think I work with that guy!

Wiki (1)

d99-sbr (568719) | more than 10 years ago | (#9535749)

Set up a Wiki somwhere and just start typing. I've found this to be one of the best ways to quickly build up a large mass of information.

Whenever you think of something that you'd like to save for the future, just type it down somewhere in the Wiki. Later when you have the time you can browse around in it and rearrange the text and improve it.

Think about how you learnt it (1)

harryman100 (631145) | more than 10 years ago | (#9535875)

You say you learnt most of this yourself? What makes you think your replacement won't be able to do the same?

I'm in a similar situation, I am leaving my job exactly a month from now, my replacement starts on Monday, so I have 1 month to pass over every bit of knowledge I can. However, there is only so much I can do, we are heavily reliant on my replacement being able to adapt and learn things themselves. Even with a crossover period, in support work, there is no guarrantee that you will be able to cover everything (unless you deliberately break things).

Originally I had to prepare for the fact that my replacement would not be starting while I was still working there, so I would have to document things, this is exceptionally difficult, you have no idea how much detail is required, as although they will be competant for the job (we are assuming that interviewing has taken place!), everybody learns in a different way.

You will only need to document things that are out of the ordinary. Think back to all those things where you'd wished there had been someone around to tell you what to do, and write down exactly what you did do. Hope that they pick up everything else themselves.

In preparation for when I leave, I have put together a 2 column table, in the first column I put "things I know" and in the second column I have put the name of the person within the company already who knows most about the tools/situation/problem/error message/process/etc. Hopefully this will help people out, rather than the new guy picking on one person to ask questions, and taking up too much of their time. It will help to spread out the burden of getting the new guy up to speed among everybody once I have left (there's more than 1 month's worth of stuff to learn). It also helps them to get to the right person almost straight away each time.

You think you know too much to document? Think about how you learnt it, can they learn it the same way?

Re:Think about how you learnt it (1)

Clover_Kicker (20761) | more than 10 years ago | (#9546682)

Aha, but did you ever screw something up while learning something?

"Experience is a dear teacher, but fools will learn at no other" - Ben Franklin

Re:Think about how you learnt it (1)

harryman100 (631145) | more than 10 years ago | (#9553323)

Did you?

And how much did you learn from screwing it up compared with how much you learnt when you didn't!?

Re:Think about how you learnt it (1)

Clover_Kicker (20761) | more than 10 years ago | (#9555636)

I've learned a tremendous amount from my mistakes.

I bet the various employers where I did the [learning|screwing up] wish I'd found another way to learn it :)

Too late. (2, Insightful)

jotaeleemeese (303437) | more than 10 years ago | (#9535900)

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.

Why oh Why (0)

Anonymous Coward | more than 10 years ago | (#9535935)

is slashdot full of people sucking up to their employer recently?

beautiful little yellow (2, Funny)

i chose quality (413813) | more than 10 years ago | (#9535947)

post it's.
a lot of them.

do an ok of job documentation....` (1)

fozzmeister (160968) | more than 10 years ago | (#9536105)

.... but not an amazing one, just say your open to contract work :-) unless its code, if your a coder your payed to document your code, not what your coding.

How I've done it (2, Informative)

travail_jgd (80602) | more than 10 years ago | (#9537534)

My first method of documentation is going through my typical workday, and writing down everything important. In the space of a week, that covers most of my tasks.

Next, look at what scripts or macros are used on a regular basis. Make a note of them, and email copies to managers whenever possible. You never know if the person who "cleans up" behind you is going to erase every file with your username.

Don't forget the 80/20 rule. Focus on the 80% first, then the more arcane aspects of the 20%. It shouldn't need to be said, but don't make comments about individuals -- positive or negative. Just comment on the needs of various areas, and try to leave names out.

Use whatever word processor is standard in the office, and type up the directions in outline format. That makes it easier to make small notes, exceptions to the rule, etc.

Email copies to your supervisor/manager and your current account. Printouts have a habit of getting lost... Keep a copy for yourself too (but don't email it). Being able to show your writing style is a major plus in interviews.

I use Leo (2, Informative)

grayrest (468197) | more than 10 years ago | (#9538783)

I actually am in the same situation as the computer guy at the school newspaper. I inherited a bizarrely complex setup that took me a year and a half to figure out and wanted to save my successor the trouble. To that end I've used leo ( [] ) to document the server setup, ghost setup, and code needed to keep everything running. Leo allows me to organize both notes and code in the same place. I've talked it over with the guy I'm grooming for replacement, and it seems to be working, he's pledged to continue the project, so I hope it works out. Good luck to you.

My job (1)

zekemacneil (595573) | more than 10 years ago | (#9541096)

I'm a clerk at a library. So I guess you could break my job down to an SQL statement: SELECT from 'stacks_3rdfloor' where 'call_number' == $callnbr. Or something like this: $ kill -9 snoring-patrons

test (1)

phoxix (161744) | more than 10 years ago | (#9544188)

Check for New Comments
Slashdot Login

Need an Account?

Forgot your password?