Spent yesterday reading through the code for Webware. I understand it a lot better -- the factoring reminds me of Smalltalk. Wrote a document trying to describe how it all fits together.

I realized that most documentation fits two models: tutorials/users guides, and reference documents for the developers. I think that leaves a big gap, for someone who wants to become a developer on the project, and is already a programmer. Being confronted with a pile of code can be very intimidating, not to mention frustrating. You change a piece of code only to find out it doesn't get called when you think it will, or you search in vain to find the code that corresponds to a certain behavior -- you may never find it, the section of code you imagine may actually be scattered across the entire program because you have the wrong model as to the inner workings. Reference documents don't help you there. At best they infer a model, in a vague sort of way.

Webware was pretty bad that way. A lot of generality, classes are often not referred to concretely (since part of customization can be creating subclasses of core components), and a mess of methods passed back and forth. Not so bad when you understand it, but I had to struggle some to figure it out. (that said, I think it is well programmed and very compact... I wouldn't want to even start were it programmed in Perl... it's just complicated and has a lot of hooks for future growth).

I always enjoy code maps, more people should write them. They address concretely what's probably the most important part of the program -- the architecture.