views:

373

answers:

8

I resigned from my current place of work yesterday, and I'm taking it upon myself to document my projects so I can hand them over easily.

Bearing in mind that my code is already commented to a good standard, what else should I put together to help my fellow developers take over my projects?

+16  A: 

When working with a new code written by someone else, the first thing that the new guy (or girl) lacks is an overview over the System. What subsystems are there, what's their purpose and where should one look to accomplish a given task at hand are some questions that come to mind.

A concise starting document, explaining the overall system design (and the reasons why this design was chosen) perhaps with some diagrams, would be something I would be really glad to get when working on a piece of software written by someone else.

Michael Barth
Agreed. Sit down and think about what you need when you join your next company.
Preet Sangha
I add another thing, (another document for the known bugs and not solved)
Ahmed Said
GenericTypeTea
+3  A: 

Personally I write all my docs in a top-down style, first giving definitions to all terms (to establish a common vocabulary) and then explaining subject in question in broad terms, refining details further down the document. So this kind of doc covering all major parts of system will do quite nicely. Also, it would be nice if you provided rationale for architectural decisions in your projects.

Anton Gogolev
Regarding rationality for old projects... How do you explain the reasons behind doing something 18 months ago that you now know is wrong... or rather wasn't wrong at the time, but you now know it's not the best way?
GenericTypeTea
I personally write all of my thoughts down in a small "easy to use" Wiki..if something turns out wrong, i just have to search my wiki...afterwards i just to talk with my colleague about this issue and write it down in my documentation. For me its important to write everything down. Sometimes it is an overkill of information, but its working for me. :-)
bastianneu
@GenericTypeTea - In that case you can document - 1) why that design was chosen at that point of time 2) why it is now considered wrong/obsolete and 3) why it could not be changed after the fact / how you were planning to change it.
Samit G.
+2  A: 

UML sequence diagrams for any complex class/system interactions, class diagrams for any more complex OO designs, and system-level diagrams that show how different systems and apps inter-connect.

Andy White
+1  A: 

You can explain the design of the project, how some important features works and maybe you can document any future enhancements you planned.

Ratnesh Maurya
+4  A: 

Consider making your top-level overview documentation a Wiki - it allows your soon-to-be ex-colleagues to edit and expand it easily.

And a rationale (as mentioned) is very useful: Why did you choose solution A, when solutions B and C look so much better to a casual observer? It can nip all kinds of endless discussions in the bud.

Harald Hansen
+3  A: 

This might be self-evident, but if the projects don't compile / run "out of the box" when checking out for the first time to a fresh development environment (of course they should), a step-by-step guide on how to get everything up and running will save the new people from a lot of headache.

Janne
+3  A: 

I wish I didn't have anything useful to say here, but as the recipient of code tranfers through several downturns, skill rebalancings etc, I'd like to repeat and add a few points to the previous answers.

I assume your management has appointed one or more people to take over your work.

You said you don't need it anyway, but this is not the time to add comments to code.

It was already pointed out that the new owner of the software needs a high level overview, what does the software do and what was needed to do it. Keep this brief, and try to not let it devolve in 'what should the software have looked like', don't bother to re-architect the system from the grave.

Then move on to practical matters: who are the stakeholders, testers and anyone else that was and may become involved and know about this software.

Where are the requirements other documentation and PRs, is there anything expecially noteworthy in the PR's are upcoming requirements?

Where in version control is the sofware, is everything in there? Really?

What's needed to build the sofware?

The most valuable time will be spent on verifying the last two points: Recreate a complete a build environment from version control and build (test/deliver) from the new owner's machine. If there's time, fix a simple problem.

Good luck in the new job!

Erik E
A: 

Someone else already mentioned documenting your entire toolchain to help someone set up the dev environment. Another thing which might be a bit too meta is to document why you use those tools.

Nothing's worse than starting somewhere new and planning to tear out all of the MS Word by the roots, only to find out when you're elbow-deep in the process that the German sales office has to have their TPS reports generated in that format and can't use the wizbang JSON you wanted to replace it with.

Jon Konrath