Assume that you're a sole developer leaving a job. What kind of information/material, outside of the code itself, should you create and leave behind for your replacement?
An obvious answer is "whatever you would want at a new job" for sure, but it's been a while since I started a new job, and I forget what the most important things that I needed were back then.
I'm thinking:
What else?
Is what I wish I was left.
SELECT * FROM clients. We aren't sure why but it dumps the database". My email address, or perhaps even phone number.
In my experience it's difficult to get every detail written down, so the best thing is to be available (to a certain degree) if your successors need more information.
Documentation of the programs you have written e.g. their purpose, location of source files for future development, passwords, etc..
This can either be within the code as a comment or outside in plain sight.
More than just documentation, I'd like to know why certain decisions were made when they were made. We're using SWIG currently on a project and one of the other developers wanted to know why we just didn't use Boost::Python. The simple answer was that the customer did not allow the use of Boost at the time. Now is a different story.
Such things will help them not only in understanding the project but also what limitations/constraints/challenges your implementation overcame. It'll give them a starting point for future maintenance and feature augmentation.
One thing I didn't see anyone else mention (although I might have overlooked it) is to document how to setup a dev environment. I realize that most of the time it's just install a few things, get latest, compile and you're done. However sometimes there's more to it than that (SharePoint is one situation that comes to mind) and documenting what flux capacitator has to be configured in what way will be very helpful for the poor soul following you.
If it is a desktop program, how to build the entire system from scratch (may be several separate programs), how to create a package for distribution (what dependencies it has, e.g. versions of .NET), and how to deploy it to servers for download if that is applicable, or burn it to a CD or DVD.
If it is a web-based program, FTP and (if applicable) SSH access to the server, and what tools are used to locally create and test the code.
If it is an embedded system, complete instructions on building the binary image, what tools are used, how to download and flash the code into the product, how to set up the filesystem on the device, if any.
I just recently left a job in similar circumstances to you (I wasn't the only developer, but there was really only two of us, so I had quite a lot of knowledge that the other guy didn't have (and vice versa, of course)).
In terms of the normal documentation stuff, it's important to document an overview of the whole system. Individual components are already documented in the code, but the interaction between components and why this does that or why this needs to talk to that component are important and not always easy to figure out just by debugging/looking at the code.
Then, for about a month before I left, every time I did something that only I could do, I wrote down exactly what happened, what I had to do, and why. This was usually a case of "there was a bug in xyz component, to fix it I knew to look in file abc because of X, then I had to do this, this and this".
Of course, I left my email address and phone number in case anything came up that they couldn't figure out on their own. I got a few calls in the first few weeks, but they slowly dropped off.
We'd all like a complete data flow diagram of the system with a list of functional requirements. More than likely you never got that when you wrote the system in the first place ! Like most places the best documentation is probably the code itself so what I would love most is well documented code. Lines and lines of comments in the code explaining what you are trying to do both technically and functionally.
The #1 rule for documentation is not what it does but why. What's the backstory on the programs that run, and what they do?
I think what I would love to see in documentations besides the usual would be what features were left out. Like why certain ideas were NOT implemented or a certain platform or method NOT used (which was otherwise an obvious choice).
This makes sure that the successor always knows what not to do or if he is more capable then maybe he can come up with a work around and make certain features work.
This is especially applicable to open source projects. Can save a lot of time and brain power!
