Web development triage part 1 – Six things you need before you work on an existing web project

As a contract web developer, I frequently work with clients who have gone through one or more developers or development agencies and still haven’t achieved the goals they want, so they bring me in to mop up and finish the project. The sooner they call me, the better, but I often don’t come in until the situation is dire. Getting up to speed on these projects is the first step to being able to move them forward, either by cleaning them up and finishing them, or recommending the client start over from scratch. Here’s the process I use, but I’d love to know how it can be improved.

To get started, you’ll need six things:

  1. Any existing notes, documentation, etc.
  2. Knowledge of the platform
  3. Pen and paper
  4. A reference copy
  5. Good backups or version control
  6. Time

Existing notes or documentation

Obviously, it’d be great if you had good docs on how the project was designed and what’s where, but that’s very, very rare. Clients don’t usually want to pay for documentation, and if the developer was the type to do documentation anyway, I probably wouldn’t have been called in. So your options are to either forget it, which is usually what happens, or to talk to the previous developer and get the info from them directly. If you have access to them and they’re willing to help, take advantage of it. Half an hour on the phone can save you hours later.

Knowledge of the platform or framework

If the site is built in Drupal and you’ve never used Drupal, you’re already at a disadvantage, because you’re going to be trying to learn both the platform and the project simultaneously. If I’m working on a new platform or framework, I like to take an hour or two to really try and understand it at the high-level. Most good frameworks and platforms today have a “getting started” guide and often a few demo projects or applications that you can play with and examine the code for. Read through the docs, look at some code, download other people’s apps if you can and look at those, just to get a feel for the style and flavor of the platform. Try and look at official code if you can, or at least projects that appear to have been coded with good practices.

A reference copy

This one depends on exactly how you’ll be handed the project, but I’m often just given access to the server or get the project files sent to me. I prefer to do my development locally, so the first thing I’ll have to do is get everything setup on my own machine. Almost by definition, this project is usually broken in the state that I receive it, but it’s hard to know exactly what is broken and I need to get it setup correctly. So I find it useful to have a version running somewhere (usually on the client’s server) that is as functional as possible. That way, when I setup my local copy, I can ensure that I have things configured correctly, and the issues I’m seeing are the things I’ll be fixing, not just me not having things setup right.

Good backups or version control

You’re going to be tearing the code up, editing, adding comments, tracing execution, etc. and you don’t want to introduce new bugs that you have to track down as well. Obviously, using version control software like Git or Subversion is ideal, but even just a simple backup of the project files will do in a pinch. The important thing is to have the peace of mind that you can rip into the code as needed, because you have a clean copy to revert to.

Pen and paper

You’ll be adding comments directly to the code, but you’ll also want to make notes on higher-level architecture details that span multiple files or folders, questions that you have that you want to remember, etc. Just keep a pad and pen by your keyboard and jot down notes as they occur to you. They probably won’t be useful past the first few hours in the project, but they can help you avoid losing track of questions or realizations you come to.


Obviously, it depends on the size and scope of the project, whether it was done from scratch or in a platform like Drupal or WordPress, and the quality of the codebase in general. However, I generally find that 2-3 hours of dedicated time can usually give me enough time to at least understand the high-level outlines of a large project, and really understand the problem areas of a small project.

Tomorrow, I’ll go into detail about how to actually jump into the code and start cleaning things up.