Reorganizing development environment for single developer/small shop

Question

I have been developing for my company for approximately three years. We serve up a web portal using Microsoft .NET and MS SQL Server on DotNetNuke.

I am going to leave my job full time at the end of April. I am leaving on good terms, and I really care about this company and the state of the web project.

Because I haven't worked in a team environment in a long time, I have probably lost touch with what 'real' setups look like. When I leave, I predict the company will either find another developer to take over, or at least have developers work on a contractual basis.

Because I have not worked with other developers, I am very concerned with leaving the company (and the developer they hire) with a jumbled mess. I'd like to believe I am a good developer and everything makes sense, but I have no way to tell.

My question, is how do I set up the development environment, so the company and the next developer will have little trouble getting started? What would you as a developer like in place before working on a project you've never worked on?

Here's some relevant information:

• There is a development server onsite and a production server offsite in a data center .
• There is a server where backups and source code (Sourcegear Vault) are stored.
• There is no formal documentation but there are comments in the code.
• The company budget is tight so free suggestions will help the best.
• I will be around after the end of April on a consulting basis so I can ask simple questions but I will not be available full time to train someone

Answer 1

Why don't you just put yourself in the place of someone coming into your situation cold? What would you need to know to be effective and efficient in your job, and get up to speed quickly? When I write documentation and create code comments, I always to write my documentation and comments assuming that someone who knows nothing about this will be reading it, and then think about what would be useful to him/her.

Answer 2

Write some documentation. Not neccessarily in detail, but enough so that anyone reading it will have an understanding of how the system works, what the different components are, and what they do. Include pointers to places in the souce code, that would be "a good place to start", if a new developer needs to know the inner workings of a feature.

Answer 3

Write some technical documents before you go.

Explain what your applications are, what they do, who the customer is, who the business contacts are. Where these apps "live" any changes since initial release with brief comments about each change, etc.

Answer 4

It would be helpful for you to go through the exercise of installing a development environment on a new machine (or VM) and get to a point where you can develop, debug, etc in this environment. Document everything along the way. That should be handy for the next guy, since they will have to do the same thing anyway.

Since there is no formal documentation, you should spend some time documenting the high-level architecture. Comments in the code should be fine when working on one piece, but (depending on the size of the application) it may take a new person awhile to figure out how it all fits together. Anything you can do to accelerate that process would certainly be greatly appreciated.

Answer 5

If you have seperate dev and production servers, and a source control server that is being backed up, that's 90% of the way right there. Just make sure that the code builds straight from source control, so try pulling it down to another machine and make sure it builds there.

Forget about code documentation, it's a waste of your time and nobody reads it. It may be helpful to go through the most confusing parts of the code and add a few comments here and there, but don't get carried away trying to comment every public function or anything like that. In the end, the new developer is going to have to dive into the code and get his hands dirty, and no amount of stale, dry documentation will avoid that. Plus, nobody maintains that stuff (espcially once they see how little it is being used), so it falls out of date almost immediately, which can actually be detrimental if someone is actually reading old versions of the documentation a year or two from now and trying to work from that.

The documentation that you SHOULD create is reference documentation about how to setup an new environment, how to deploy the code, what your strategy for making changes was, etc. You should also leave a "why we did stuff a certain way" document that will be read through once just as a intro to how the code got where it is.

Answer 6

Start with the list you've included and keep fleshing it out (20 minutes at a time).

Don't worry about formatting, just keep pumping things into documents.

The most important things are

1) Who is using the product? This is a really tricky one for new developers in a small environment. Remember that entry point you setup so that the Sr. Partner's cousin's startup could embed your site through that iframe? (The new guy won't)

List all the entry points you can think of and whether they're still being used (kill the ones that aren't before you leave, but leave them in the documentation so that when someone in a year says "like we did last time" the new developer will have a place to start)

2) An "n"Step guide to setting up a development version on a laptop

1. What's the best way to setup the DB (scripts? backup from live? backup from dev?)
2. What 3rd party dev libraries are required (sometimes it's enough to open the "sln" file after a checkout)

3. What is everyone used to as far as dev-test-stage-test-deploy

   ..... get a wino to come in from the street, put them in front of a clean laptop with a stock install of VS or SharpDevelop or whatever and have them go through the setup .... you'll see the holes in your docs quickly.

3) Give management the passwords, list the accounts in the documentation.

The fact that you're asking indicates that you're a professional so i don't think you should be too worried .... as long as the new developer can compile and run a current version on their laptop the rest is their job.

Good Luck/