Document!

January 9, 2009 1:35 PM

Web site source code documentation - what is crucial/acceptable/required to demand from a vendor to be comfortable that a new web team could hit the ground running?

I have a vendor wrapping up development of a website with an ecommerce back end and a MySQL database. I had in the the contract that they owe us appropriate documentation with the delivery of the source code at the end of the project. They are pushing back and saying that their code commenting and existing open source documentation on the internet (Drupal, UberCart) should be sufficient for any new developer. I am not so confident but I don't know how to specify exactly what I want. Can anyone give me an idea of the absolute critical info I should demand on delivery? Database tables? Filenaming conventions? Credentials? What else??

posted by spicynuts to computers & internet (11 comments total)

It is entirely possible that their code commenting is sufficient. Not likely, but possible.

You need to identify what your "new web team" would actually be doing. Are they managing the system? Continuing development? Trouble-shooting? Bug-fixing? All of the above?

Each different activity the new team needs to do could require a slightly different set of information and without knowing the scope of the project it's very difficult to say what you'd need documentation wise.

Knowing only what I know, I'd want a completely comprehensive list and description of each change made to the base 3rd party components (Drupal, UberCart). Run a diff against the code the send you and the code you can download, any differences need thorough documentation.

I'd want to know exactly how everything fits together. Every piece of glue needs to be thoroughly explained in a way that doesn't require reading source code.

I'd want the code documented in a PHPDoc compatible format, although that might be asking too much after the fact. Among the things I'd want documented that way: every file, class, function and constant written by the people.

The location and purpose of any configuration scripts or files.

I'd also tell them you want a one page document giving a high-level overview of the system that you can hand to new developers to help them acclimate themselves to the project.

There's probably a bunch more. That's just what springs to mind.

There is no such thing as too much documentation. Get every piece you can. If you ever write a contract like this again, it helps to define exactly what kind of documentation you want.
posted by toomuchpete at 1:53 PM on January 9

Yah I came to the contract late and got in what I could. Documentation would be for the purposes of:

1) consulting on stability and then optimizing
2) new development on top of existing code
3) bug fixing
posted by spicynuts at 1:59 PM on January 9

They are probably wrong.

You don't need them to reproduce materials from the open source projects, but you do need them to produce documentation on the structure of the project, the architecture of the system...the "why" and "where" of everything.

Also helpful is any build/test/automation/deployment scripts that they have.
posted by mmascolino at 2:05 PM on January 9

This sounds like a LAMP deal, so you'd want documentation on:

Apache - their Apache configuration file

mySQL - any passwords, how the various grants are set up, users, etc.

PHP - That has a lot of configuration options that vary by webserver. Get all of that. You want that PHP.ini file.
posted by adipocere at 2:10 PM on January 9

If this is a bog standard Drupal implementation with a by-the-book implementation of UberCart, they should not need to provide a huge amount of custom documentation.

For subsequent development it behooves you to find a developer with Drupal and UberCart experience. One of the benefits of using well-known systems is that there are some constraints on the way code is developed within those systems that enable experienced developers to get up to speed quickly. Files for new modules (or whatever you call them in Drupal) usually have well-known locations, there is a defined folder structure, etc.

If there are any database credentials or other system credentials that don't appear in the code (there shouldn't be) or credentials to other systems that they set up (did they set up your payment gateway?) they should make sure you have all that.

If they made any customizations to the core of Drupal or UberCart, they should provide documentation stating where those customizations are and a couple lines about their purpose. If the customizations are complex they should go into a bit of detail about the structure.

If they implemented any custom Drupal modules they should note them and provide a bit of detail.

Database tables are probably Drupal standard, or standard for the implemented modules. If they have built any custom tables for custom modules, then that should be noted in the module documentation.

If you are lucky there are file naming conventions. At this level of development I wouldn't be too worried about it.

If there are whole new classes, etc. as mentioned above some class-level documentation would be nice. It really depends on the complexity. If it takes me longer to write the documentation for a component than it took to write the component itself, I generally consider the code itself to be adequate documentation. Of course, than can depend on the coder. If they did a crappy job, then extra documentation can help, but that's little consolation.
posted by rocketpup at 2:12 PM on January 9

The stuff suggested by adipocere you likely have access to yourself, depending upon the hosting arrangement. Are the developers hosting it for you as well? If so, you should get all that from them, yes.

Otherwise, if they are handling deployment to the hosting environment and you don't have anyone with the skills to get in there yourself, you should make sure they also send you the complete source code, with database scripts, etc. as well as the configuration files mentioned.
posted by rocketpup at 2:15 PM on January 9

At a minimum I'd want to know:

how to startup the system
how to shutdown the system
how to backup the system(either hot or cold backups)
any passwords used for each part of the system (database, admin, etc..)
how to deploy to a clean system
database info (tables, etc..)
posted by bottlebrushtree at 2:22 PM on January 9

Good advice so far.

In my experience, handing off a bunch of code from one team to another, without the two teams ever interacting, can very easily end up being very frustrating for the new team. Something that to one team is obvious and common sense, and therefore not worth documenting, can be completely baffling to another team.

I agree with toomuchpete that a high-level overview is key. Also, the high-level documentation should not just describe how the code is structured, but why it's structured that way. The new team will be able to figure out how the code works by reading the code and the comments, but if nobody ever writes down why it was written like that rather than some other way, the new team will have no way of knowing.

There is no such thing as too much documentation.

Nearly every programmer I know would disagree with this statement in general (in practice a lot of documentation is produced because management requests it, rather than an actual need for it), but I agree in this case. They aren't going to have any interaction with the new team, so if they leave something important the new team is out of luck. Ask for everything you can think of.
posted by burnmp3s at 2:22 PM on January 9

Oh I'm sorry I did not mean to imply that they would not have any interaction with the new team. We are working on a transition addendum giving us something like 20 hour of consulting with them and new team.

Also, they are stating it is a standard Drupal config with basic Ubercart install with only a few custom modules. I'm not entirely convinced, but rocketpup's comment is enough to assuage my fear that it will be a complete mess.

They are not hosting and I have all root level admin rights to the server, to PHPMyAdmin, MySQL, backups, etc.
posted by spicynuts at 3:40 PM on January 9

They are pushing back and saying that their code commenting and existing open source documentation on the internet (Drupal, UberCart) should be sufficient for any new developer.

For a Drupal site, there are a couple of specific things that you will want -- nay, NEED -- documented. We do a lot of gigs cleaning up after initial builds, and most of our work ends up being digging around and discovering this stuff and writing it up for clients.

1. An overview document listing all of the modules being used on the site, and the relevant settings. Details ("X is checked and Y is not checked...") are less important than a road map of what pieces are doing what, and what relevant features from different modules are being used.


2. A list of each view used on the site, where it lives in the site structure, who has permission to see it, and what it's used for.


3. A list of each content type in use on the site, who has permission to create them, and what custom fields have been added to them with the CCK module.


4. PHPDoc and a functional overview in a README.txt file for any custom module written for the site specifically.


5. PHPDoc and explanatory comments for any custom code in the theme beyond the normal tpl.php template files. Basically, if there's code in the template.php file, they should explain what it's doing.


6. Explicit documentation and justification of/for ANY changes to existing plugin modules, or core Drupal files, and an accompanying .patch file that can be re-applied to the files if you need to download a replacement version of the 'orginal' unmolested code from drupal.org.

You may want more, and some of those pieces may be hard to come by if they want to tie things up quickly, but that covers the stuff that we see causing the most problems when it's missing.
posted by verb at 9:35 PM on January 9

Whoops. On reading subsequent posts I realized I was sketching out stuff that you'd want to know if they were really on their way out the door. If you have ongoing hours with them, the stuff that rocketpup mentioned is a good bet; super-detailed inline code comments aren't quite as essential if you're able to ask them questions, but overview documents explaining what the different pieces are and why they're needed/what they depend on are really useful.
posted by verb at 9:43 PM on January 9