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.
-
Full system test specification for the whole system.
jop : +1. I'll ask my friends to vote for this too. :)Greg Dean : It appears that you have 7 friends. Stop using SOFrom David -
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.
From brian d foy -
A high level roadmap. Where do I find the major functional areas, and how do they tie together?
From Andrew -
Doxygen (or doxygen-like) documentation for the source code. Completed, please, no forgetting to write the tags for half the classes.
From Throctukes -
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? :)
1800 INFORMATION : You mean "8 meters of written documentation", right? http://thedailywtf.com/Articles/Very,_Very_Well_Documented.aspxFrom Suma -
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.
From Arne Evertsson -
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'.
brian d foy : Along with that, what sort of beer they like to drink so you know how to bribe them :)From TK -
A Good (TM) description of the problem domain and what the application is supposed to do.
6eorge Jetson : Agreed! When the problem domain is well understood, the typical slew of use cases can be refactored/reduced to an underlying core set. Programming against this core set should position the app to be within small solution domain tweaks to address the "edge case/last mile" requirementsAndrew : The business should be able to supply that. It shouldn't need to come from the previous team.From Torbjörn Gyllebring -
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.
From Greg Dean -
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.
Arne Evertsson : Interesting answer! I didn't think of the political aspect.From Amir Arad -
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.
From Ash -
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.
From questzen -
Step-by-Step disaster recovery procedure.
From Andrew Taylor -
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.
From Peter Boughton -
For databases ERD. All else, unit tests.
From David Robbins -
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.
From Carl -
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.
From Glomek -
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.
- LM
From louism -
A list of administrator logins.
From elmnoise
