Follow Slashdot stories on Twitter


Forgot your password?
Communications Technology

How Would You Document Your Job? 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?"
This discussion has been archived. No new comments can be posted.

How Would You Document Your Job?

Comments Filter:
  • Three (Score:5, Funny)

    by SpaceLifeForm ( 228190 ) on Friday June 25, 2004 @11:50PM (#9534903)
  • by ahknight ( 128958 ) * on Friday June 25, 2004 @11:51PM (#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'!
    • 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?
      • 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.
        • by Glonoinha ( 587375 ) on Saturday June 26, 2004 @10:02AM (#9536738) Journal
          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.
      • 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...

      • He did use the word 'imagine', no?
  • and do it all in l33t...

  • why? (Score:1, Insightful)

    by 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?
  • WikiWikiWiki (Score:5, Informative)

    by BortQ ( 468164 ) on Friday June 25, 2004 @11:54PM (#9534929) Homepage Journal
    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.
    • by OldMiner ( 589872 ) on Saturday June 26, 2004 @12:03AM (#9534968) Journal

      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.

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

  • Quirks (Score:5, Insightful)

    by Kris_J ( 10111 ) * on Friday June 25, 2004 @11:57PM (#9534945) Homepage Journal
    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 (Score:5, Interesting)

    by ahknight ( 128958 ) * on Friday June 25, 2004 @11:59PM (#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.
  • 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.
  • 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.
  • Don't document anything. It's called job security, you fool!

  • by MerlynEmrys67 ( 583469 ) on Saturday June 26, 2004 @01:03AM (#9535200)
    1 Learn Hindi
    2 ???
    3 Profit
  • 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 nee
  • 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 t
    • 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.

      • 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.
  • 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 (Score:3, Insightful)

    by SmallFurryCreature ( 593017 ) on Saturday June 26, 2004 @01:55AM (#9535368) Journal
    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... (Score:3, Informative)

    by cornice ( 9801 ) on Saturday June 26, 2004 @02:06AM (#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.
  • 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. ;-)


  • 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.
  • 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 ev
  • Too late. (Score:3, Insightful)

    by jotaeleemeese ( 303437 ) on Saturday June 26, 2004 @05:26AM (#9535900) Homepage Journal
    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.
  • post it's.
    a lot of them.
  • .... 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 (Score:3, Informative)

    by travail_jgd ( 80602 ) on Saturday June 26, 2004 @12:25PM (#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 (Score:2, Informative)

    by grayrest ( 468197 )
    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 t
  • 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
  • by phoxix ( 161744 )

May all your PUSHes be POPped.