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

Question

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.

UPDATE:
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.

Answer 1

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.

Answer 2

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

Answer 3

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.

Answer 4

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.

Answer 5

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.

Answer 6

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

Answer 7

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.

Answer 8

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

Answer 9

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.

Answer 10

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.

Answer 11

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.

Answer 12

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.

Answer 13

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.

Answer 14

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.

Answer 15

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.

Answer 16

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.

Answer 17

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

Answer 18

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.

Answer 19

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

Answer 20

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.

Answer 21

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?

Answer 22

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.

Answer 23

Ideally none at all.

Why?

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.

Answer 24

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.