You are joining a project to maintain an existing system. There is no written documentation at all, but the previous team offers to write one piece of documentation. And they are going to let you decide what it should cover: What is the single most important piece of documentation?
This is a poll: give only one document type per answer and let other readers vote.
If I can only get one part of the documentation, I want to know the overall design and how things are supposed to fit together and work with each other. The hardest part of any new system is figuring out the landscape. The rest is just work.
A high level roadmap. Where do I find the major functional areas, and how do they tie together?
Doxygen (or doxygen-like) documentation for the source code. Completed, please, no forgetting to write the tags for half the classes.
Crazy question - "one piece"? What is the "piece" of documentation?
My request would be to create a "complete documentation, at least 500 pages of written text". Is that one piece? :)
How to set up the development environment: A step-by-step instruction which gives you a complete environment in which to check-in/check-out code, build, debug, deploy, test, run and perform all your daily tasks.
Contact details for the original development team.
Failing that, I would definatly say a software build document describing how to manage, modify and build the codebase. Alongside a list of known 'gotchas'.
A Good (TM) description of the problem domain and what the application is supposed to do.
Detailed requirements of what the application is supposed to do. Good luck though, I have never managed to get this. Even from an army of documenters, willing to write billions of documents.
obviously there's no real answer to this situation. whatever technical documentation you choose, you're going to have to dig into the system and figure it out. IMHO, and I'm not trying to be a smart ass here, the most important piece of documentation in this case is "how things got to be the way they are"- an organization politics/resources review of the conditions that led to the "no documentation and project is being transferred to another team" situation.
Not documentation in the traditonal sense, but a virtual machine or ghosted image of the working build/test machine would be very useful.
How to set up the development environment would be most useful though.
For existing projects, assuming that the testing is end to end, the test scripts act as an accurate source of status-quo. Most often documents don't get uplifted to represent the updates, but test cases are. However, the test cases are seriously limited in that they fail to provide the rational behind why the system is designed so/exists so. An architecture diagram is needed complement this.
What the business rules & reasons for each decision are.
Everything else can be done by any good developer - but without knowing the business reasons for functionality, you're doomed.
Project log - we're great believers that when key decisions are made you should be recording why you chose to go down a particular route and more importantly why you chose not go down an alternative route.
Having this in place helps to stop future developers from making the same mistakes again and wasting a lot of time.
I want the docs for all of the data structures. When and how they are used, what each of their members are, and what they store. I especially want to know how the data structures map to the problem being solved. If I understand the data structures, then I can often skip most of the code, because I can guess what it does. If I don't understand the data structures, then I need to read a bunch of code to figure out when and how they are changed and what they're supposed to hold and why.
this is a pretty good question, not that you would ever get a situation like this (you will generally get zero documentation).
my choice is a toss-up between two things: a system test plan as others have said, so no surprise there. reason being is that test-cases teach you how the software works. at least the style of test plan i use does (i did a blog article on this, shameless plug -> http://pm4web.blogspot.com/2008/07/writing-system-test-plan.html).
the other one i would go with, and this may seem a little strange, so bare with me - is a project schedule. i dont know how relevant this would be for an already established system, but i have had it a few times now where ive arrived at a new company and been greeted with a disaster zone (i.e. projects running behind schedule, clients laying siege to our office, etc). the single biggest help would of been if i stopped and created a project schedule, outlining all the tasks needed to achieve the business objectives. you cant create a decent schedule without understanding the system along the way.