Wednesday July 25, 2007

Make it happen.

By Colin Lieberman

The desktop software industry knows all about documentation. But in the web shops where I’ve worked, documentation is a dirty word.

The truth is, your web app needs proper documentation and you know it. If you bring on a new developer, he or she must be able to find out how you are supposed to be calculating tax, or what the user login report is supposed to calculate, without having to “go ask Bob”.

Now, if you only turn out 300 page brochure sites that you forget about the day after they launch, you can probably get away without documentation. Anything you’ll have to maintain in the future though...

It’s Easy

There’s a lot of resistance to documentation, and that resistance is born of fear. The truth is, making documentation happen is easy.

So I told him...

Here’s what you say to the boss:

If there’s still resistance, you’re working for someone who doesn’t value your time or sanity. Quit.

The wrong tools for the job

There are some commonly used documentation tools you can forget about right now:


Let’s all have a good chuckle and move on.


Basecamp is good for organizational direction, and for some initial requirement gathering, but I find it too cumbersome and badly organized for real documentation.


How many copies of important word documents are running around your office? I’ve got 10 bucks that says there’s someone in your organization who refuses to keep anything on the shared drive.

What does work?

Wiki. Wiki, wiki, wiki. If you want to get fancy, you can limit who’s allowed to edit it, or you can force all changes to be passed via an editor for acceptance. But a good wiki is searchable , flexible, and easy to use.

More than the tool though, making it happen is the process:

What you must do is convince the people you work with that documentation is part of the project. This worked for me:

It’s no different from completing time sheets. That’s not optional: we must be able to bill clients accurately. Same with documentation. We must be able to have documentation to refer to. It’s part of the job as much as timekeeping is.

Baby Steps

Don’t say “we’ll start this with the next big project.”

Don’t say “this project’s a mess, this is pointless.”

Don’t say “god damn it! This should have been done a year ago!” (no matter how true it is).

Try this: “starting today, I’m going to document all new features and changes as a I do them. I’m going to treat documentation as a key part of my job, and I’m going to include documentation time in all time estimates I give anyone. If I’ve got a few hours to spare, I’ll go back and document some of the features I did six months ago.”.

Good luck.


  Textile Help