Key Site Concepts: Documentation

This is going to be the first in a series of key concepts for your site that should help to make it a better place for all those involved.

About two months ago I changed jobs, going from being a do-everything developer/database administrator/IT guy for a research study to being a database administrator for a mid-sized company. I spent most of my final two weeks at my old job gathering documentation, commenting code, and training our junior developer how to do as much as I could. Then I came to my current position, and struggled a bit with the transition for one clear reason...nothing was documented!

I know what you're thinking..."Wow, Greg...that stinks, but what does that have to do with my church's web site?"

In all honesty, it probably means a lot more than you realize.

Documentation is a key element to any kind of programming, and it applies to all web site work whether you work with ASP, ColdFusion, PSP, or basic HTML. However, many of us programmers are not always good at keeping up with our comments and documentation. Most of us are convinced we can just read the code anyway. However, I know I've gone through a few late-night coding sessions and regretted not keeping up with my documentation.

Some other good reasons to keep up with documentation:

• You're Not Going To Run Your Church's Website Forever - Probably the most important reason to document the code that you create. It gives the next person to come in or additional people coming on board an insight into what you've been trying to do. It helps them get up to speed faster. This can also be a real time-saver, as I know I've seen more than one webmaster decide to "reinvent the wheel" for their site because they couldn't decipher what the last webmaster was trying to do because nothing was commented.
• You May Not Update Pages Frequently - Chances are there are some pages in your site that don't need updated very often, but you want to make sure that you don't forget what you did on them and why. For example, you may use a content management system but make a lot of changes to customize it for your uses. If you don't document these changes, you may forget why you made them and accidentally change them and lose something. With properly documented code, it's easier to make the appropriate decision for the changes you want to make.
• Comments Make Great Notes - When you are putting together code, you may want to make a change somewhere but haven't decided the best way to do it or you just don't have the time to do all the coding right then. Instead, you can leave comments as reminders to yourself as to what you'd like to do. It's a great practice to get into, and it also keeps you from forgetting to do things that you think of while you're working on something else.

I know, I know...documentation always sounds boring and mundane. Many people even feel that it slows them down in their work, but any good programmer can probably tell you about how much time they've saved in the long run by taking the time out to complete their documentation when needed. If there were ever a lesson to take from the corporate world of software development, it's this one!