I'm involved in a project where it's in a state that works well for the client, but ultimately needs a lot of intricate supplementary work for future success. If I left tomorrow, the other developers here (well, all but one of them, but he's working on something else) would have a difficult time managing what's been accomplished already, and what the project needs for the future, simply out of inexperience.

So, I am asking, what, if any, documentation should I leave behind before quitting this job? Anything beyond the normal documentation involved with a project?

I'm balancing between (a) leaving nothing, having the project fall flat, and me not looking very good for not finishing it, and (b) writing a bunch of documentation that I shouldn't be responsible for anyway.

Any thoughts on the subject would be appreciated.

I think this all comes down to ownership. In this case, I don't own any part of the project; all I've done is contribute to it. I think that's where I'm getting confused. I started the project from scratch, so it feels like it's mine... but it isn't. I gave up those rights by signing my employment contract. What the ownership (management) wants to do with the project is up to them, and them only. I have the latitude to do what they want in my own way while still contributing positively to the company, but that's it. I am responsible for what I do and how I do it; business decisions are the management's responsibility.

I'm going to accept an answer here because I think the idea behind it is sound; however, I would like to turn a lose/lose into something better. One way to do that would be by writing an additional document describing the current state of the project. This would at least give management the information they need to direct my successor towards achieving their business goals. Even if I end up as the fall guy, at least I've told them about the shortcomings of the project without them having to find out on their own. I think that is worth a lot. (Note: the project actually is not in a poor state; this was just an example of a worst-case scenario.)

Everyone who posted here has good ideas, and I thank you all very much for contributing. Additional comments are certainly welcome.

+2  A: 

Definitely don't do choice 'a'!

I would start adding points and pages to a Wiki to cover:

  • notes on current design,
  • possible future extensions,
  • maintenance hints,
  • etc.

Using a Wiki means it is easy to migrate points from the future extension to be used in the current design section as things get done.

Rob Wells
+1 for using a Wiki. I didn't think of that (everything is in Word format in source control).
Jon Seigel
+2  A: 

If you want your boss to give you references, write a lot of documentation. The content isn't that important, he will weigh it rather than read it

Why the downvote? It's true (but sad).
I up voted you because you are right. It is pretty sad though.
In my case, I think there would be a roughly 80/20 weighting between how happy the client is with the product, and the internal documentation that goes with it. I think if my boss was concerned more with sheer volume of documentation, then he wouldn't be a very good boss. You could be right, though.
Jon Seigel
@Jon: Of course you are right in the short term. But when you quit there had better be documentation, or its going to be very slow to implement new features that the client wants. Your boss' appreciation of you at this time will be a direct function of the weight of the documentation since that's much easier than judging the quality of it.
Writing bad docs will only be bad for your reputation - thus making it harder to get jobs.
+32  A: 

You're in a no win situation as once you leave you are the easy fall guy for whatever standards and process weren't in place when you were delivering. I say send an email asking your supervisor for a list of action items he'd like completed before you leave. Deliver on what he asks and nothing more. That is your job: deliver to the expecations of your direct superior. Any shortcomings or lapses will fall to his/her management of his people.

Nissan Fan
I agree -- the problem of having only one dev that is capable of understanding the system was not caused by the dev, it is a result of management decisions.
Guy Starbuck
In my experience, some companies economize by terminating your employment after you give notice but before the day you planned to leave. This shows, more clearly than words could, what their financial commitment to the project's continued success is.
Steven Sudit
I disagree that it is a no win situation. What he knows might be desperately required at a later date at which point it is very much a win situation. But I like your advise.
we all know that many times managers are just random people taken from a street, one of my managers used to be homeless.
+2  A: 

You should be training one or more developers on the system/project. Your combined notes then become the basis for the documentation. If you are kind you will organize it and fill in any gaps. But running it like a training seminar puts the onus on the developers to learn as much as possible and frees you from writing endless docs that probably won't get read anyway.

Byron Whitlock
+1  A: 

What about a mix of a and b? I know it's a pain but having some documentation it's better than nothing, I will start some documentation (We use a lot of wikis) somewhere and help the guys go through the hardest things to do, maybe they can follow with the not-that-hard things to do later.

Some documentation is always better than none, also helps you to keep your doors open and it's the correct thing to do.

+1  A: 

I would try to get the other teammembers up to speed on the codebase.

I plain documentation thats rushed usually is not doing any good. Try to organize some pair programming session etc, so that the others in the team also feel like they own some of the code.

It all depends on how much time you have available, and what you think would be best for the other team members

Heiko Hatzfeld
+8  A: 

The fact that you quitting leaves the project unable to progress or be maintained speaks volumes about its management. You should alert them about these shortcomings, establish a course of action and if they are smart they will take action so any developer leaving (not only you) does not abort the project. This means some extra documentation work for you, but your bosses will either consider you highly for being so professional or (in the worst case) they will do nothing in which case you can leave with you conscience clean.

Otávio Décio

Depends upon the company. Better you hand over your works to some one and quite the job . If not how company can manage the business :)

Knowledge sharing should be there ,

  • Give document
  • Further extension etc
+5  A: 

I would say do not write any formal documentation. What should be done is your company should pair you up with someone that is likely to pick up your responsibilities. He will then write the said documentation while you are around. This way it will be done by someone currently employed and is more easily updated and maintained. The person documenting can also ask you questions you may not account for in your documentation. It will also lower the possibility of something being left out of the documentation due to you having the notion that is was "common knowledge"

We recently had a guy move on and he wrote very detailed documentation of his tasks, but once we referenced the doc it wasn't that information we needed. Most of the time you need judgement calls that come along with knowing the module. Getting someone else to know first hand what you've been doing will be a great leg up.

If you don't have someone to put this knowlege on (everyone is booked) then it would be better to give very high level descriptions of things. Useful links to relevant material and what everything generally does. Anything more then that will be overkill.

The last paragraph is the case around here. I documented the most intricate stuff from a high level, which I hope is adequate.
Jon Seigel
+3  A: 

Interesting that this kind of question should come up now, since I'm about to deal with the same issue. The project I'm responsible for was written by a past, less competent developer, so there are many...subtleties in how it works.

My solution, aside from refactoring a great deal of it, is as follows:

  • Write extensive Xml comments (I'm in a .Net shop) for everything, since the project currently lacks such attention.

  • Write a 'Concept Doc', explaining the overall point of the application, reasons for how individual parts of it works, tips on what to look for should a particular exception rear thy ugly head, and a large section on the more eccentric bits and how to deal with them. I'm writing it from a candid perspective, with bits of humor scattered throughout so as not to bore the application's future caretaker to tears. There is documentation on the application presently, but it was drafted by someone who didn't write the application and barely understood the domain.

  • Sitting down with the developer that will be taking over and stepping him through the entire application, using the Concept Doc above as a general tour guide.

With any luck, the next developer on it should be able to, at the very least, know to check the session related components when he sees a "No Index at Position Zero" error, because some of the code makes unsafe assumptions.

+13  A: 

Once you resign, it is quite literally no longer your business, so it's not your call at any level. Instead, you're offering two weeks' notice with the expectation that the employer can take this opportunity to request documentation and training. If they'd rather you do something else, that's their decision.

Steven Sudit
I understand your point, but at the same time I want to take responsibility for my involvement with the project.
Jon Seigel
This seems kind of hostile. If the company has treated you professionally and courteously I think they should have every right to expect that you have been documenting your code all along. Hopefully though your manager will think to ask that question while there is still time to create any documentation. I've been in my current shop for over 13 years and could not document everything in two weeks.
@Beaner: Yes, the company presumably already has standards for documentation, which you've been following to some extent. It's therefore up to them to evaluate the existing documentation and decide what gaps they find and care about. It would be appropriate to suggest gaps but not at all appropriate to decide for them just how you'll be spending your last few days. No hostility involved, but you're not going to be working there anymore, so it's not up to you to impose your decisions upon them, even if your intent is good.
Steven Sudit
@Jon: You're certainly responsible for what you've done and should be willing to train your replacement. And I'd recommend a walkthrough over just paper documentation. However, as much as you'd like the project to succeed in your absence, there is a limit to the extent that you are able to make it do so. It may well be that you care more about the project than they do, in which case it would be up to them to decide whether it *should* be allowed to fail. Remember: it's their business.
Steven Sudit
+6  A: 

Regardless of the current state of the application, I've been in the process of writing "white papers" for the apps we create around here. It is typically about 1 page long and contains:

  1. Who requested the app.
  2. Which department(s)/group(s) are involved.
  3. The date the app was requested.
  4. The estimated delivery date of the app.
  5. A brief description of the apps functionality/purpose.
  6. The justification for creating the app.
  7. The high level architecture of the app (A web based app that interfaces with the third party system to spit out pretty crystal reports.)
  8. The developers and primary folks working on the app.
  9. The application architecture (SQL 2K5, IIS 7, C# 3.5)
  10. Any dependencies (systems/libraries/applications) the app has.
  11. Any "gotchas" or issues of note (Such as the customer still doesn't have their third party system with clean data, so duplicate records have to be manually filtered out)

Leave this document physically and digitally with your boss or whomever is going to take things over. I find this the proper balance that gets somebody off to a good start with working with the application without having to document yourself to death with every jot and tiddle.

I don't think this answers my question directly, but +1 for a good idea for any project.
Jon Seigel
I guess my "long" answer would be to do a document just like this. To some degree you aren't committed to providing everything if it hasn't been done already, but by the fact that you're asking indicates you're a quality developer who wants to make sure the project continues to succeed and having something like this goes a long way.
+2  A: 

I would document my code because no matter how the company is treating me I want to do work I can be proud of. If your code is well commented then your documentation job is (at least mostly) already done. If this is a large and complex project then of course documenting it is going to be difficult. Also, if you get the documentation done and decide to stay you must keep the documentation up to date. That is another reason I prefer documenting with in-code comments. I get along well with my co-workers and taking nothing for granted I try to document my code as I go in case I am fired tomorrow. I use a combination of comments in code, and flowcharts. In the rare case of a really complicated piece of code I will explain what it is doing (or why) in a separate document. My shop uses a wiki so I can upload my flowcharts to there and link additional comments as needed. It is also understood between the programmers that if we have a need we can call or email each other.

+3  A: 

Here's a lightweight way of producing a workable handover (or any documentation). Get a video camera and 2 or 3 developers who might either be taking on your code, or are at least in a position to understand it.

Give a presentation on the system to your audience, 20 - 60 minutes depending on the complexity. Draw lots of diagrams on the whiteboard, maybe point out sections of code. Have them ask questions during and at the end until they are reasonably happy that they know enough about the system. Videotape the whole thing.

If you have time you can then go and annotate the video with whiteboard prints and code samples. Publish the results as your handover documentation.

The whole process can take under a day. Unlike writing documentation, the interaction with your audience ensures that vital areas are covered, without having to say everything in great detail.

Duncan McGregor
+1  A: 

As mentioned earlier, ask your supervisors what they want completed both code-wise and documentation-wise.

Having said that, what would you want to find if you came into a situation like the one you're leaving behind? Do something that approaches that.

+1  A: 

Tough choice all around. I'd agree and disagree with many that have posted and would add only a few remarks:

Document everything you did. If there are portions you did not take part in designing or implementing state such but give a general overview of what was expected, how you worked with it, and what can be improved. Not only will this engender yourself to future developers who may or may not take over the code base but it will also provide guidance to management.

If you're worried about the project blowing up after you leave then you have to ask yourself two questions: Did you come up with "clever" solutions or leave "tricky" parts of code behind you which will make the project fail? Will the other developers based on their programming capabilities be able to continue work in a productive fashion? If you can answer "no" to the first and "yes" to the second then it's not your concern despite everything. You've done your best.


It on depends how much you liked the people you were working for :)

+1  A: 

I think they are to blame for not managing their IP very well by ensuring the next guy can get up to speed easily.

Actually it can often turn to your advantage as the knowledge in your head might be vital to their business at a later date and you can charge them a nice hourly rate plus travel for it.

+3  A: 

be honest with your employer, give reasonable notice, offer your services as a contractor

Dustin Getz
+3  A: 

What, if any, documentation should be written before quitting a job?

If I were maintaining software then I'd like to know:

  • Its functional specification: the definition of what it's supposed to do
  • How to build, deploy, run, and test it.

Given all that I can probably figure out how it's implemented, how to debug it, and how to modify/extend it.

+1  A: 

Unfortunately (in my opinion) many companies just don't see lost knowledge/experience, when a developer leaves, as being an important issue.

They are completely happy to work harder, not smarter by throwing some unfortunate replacement in at the deep-end to learn the intricacies of the system on the job.

So, when I was in your position, the decision over documentation depended entirely on how much I had grown to respect direct colleagues (eg fellow developers) I worked with.

It is for these people that you can decide to make the next few months after your departure either bearable or possibly a nightmare. So whether or not the company management gives a stuff, I just focus on how these colleagues will be affected.

Many developers I've worked with have a phobia of documentation in general and just don't have the mindset of writing code for "other people to read". In this case leaving the nothing or the bare minimum may help them to see the error of their ways.

However for others, especially those who you have worked well with and struck a friendship with, I certainly would go out of my way to ask them directly what would be most useful sort of documentation and then do it, with or without management knowing.

So, in summary, if the development team has their heart in the right place, but are perhaps struggling against poor software management processes, I'd suggest leaning towards providing basic documentation at the least. On the other hand, if the development team and management, just don't seem to care, why should you?

+1  A: 

I'd try to do as much of (b) as you reasonably can, but focus on exactly what you think your successors will need, not on low value documentation. Don't forget that you'll also be able to answer a reasonable number of questions after you leave, and that perhaps you can do a bit of consulting for your old company too.

Jim Ferrans

Ideally none at all.


Well - documentation doesn't really transfer your knowledge all that well. If you're going to do it (and own it) then you should be writing it as you go. It should never be more than a month out of date.

If you've got a single month left of your notice there are far better ways to transfer your knowledge. Get whoever's going to be working on it to start now. Then you can mentor them as they learn the system.

A month of basically pair-programming/tutoring will teach them an awful lot more than a chunk of docs ever will.

If this can't happen, say because you're the only dev and no-one else is going to be available until after you're gone, then that project is dead. By the time somebody finally does look at it they'll bee too late and too detached and they won't have your knowledge to call on.

Incidentally even if you don't pair program you should never have developers solely 'own' code. Not only does it create this situation, but it also stops them ever getting promoted (we can't give him the exciting new project, he's the only guy who understands this legacy system). You might be the best dev on a project, but you should never be the only (or only competent) one.

Finally, leave your phone number and your flat day rate for consultancy. Tell them you're happy to come back an help at that rate if they need it.

+1  A: 

Assuming you're going to quit, then probably the way you can be most useful to your company is to write a "Dear Next guy to Work on this project" document, and so that's probably what you should do. It should try to capture as much of the current state as possible: what for the client at the moment, what intricate development you think needs to happen at some point, what may need some TLC. If the only answer is "either scrap it or hire an expert", you could even make that clear.

Dillie-O's answer was extremely excellent suggestion for where to start on that.

If your boss and colleages are willing, then talking someone through this would be extremely useful, but even if not, they'll appreciate it later if they try to continue. If they actively obstruct you, then so be it.