As an addendum to Dave's comments, it's probably worth pointing out that the existing packages we've inherited demonstrate a wide range of styles in using the core functionality, some easily branded as being "wrong", others as "right". This is frustrating because overall they don't provide a good model for producing a well-written package.
Partly this is a natural outcome of parallel development, i.e. people being asked to produce packages as core functionality was being written. Partly this is due to the very lack of documentation Dave mentions, and partly due to uncertainty and experimentation. The core designers/developers hadn't yet thought things all the way through and there wasn't sufficient direction available for package implementors. These problems stemmed from (lack of decent engineering) management, more than anything.
None of this is meant as a knock on aD developers - extreme time pressure nearly always leads to a lack of documentation, in particular. Of course it's just my opinion (based on some conversation with a couple of folks who were at aD at the time), not gospel.
Over time we need documentation of the type Ben's talking about. We also need to look into simplification where simplification makes sense (we don't need two separate database APIs, for instance), more higher level tools (service contract editor, easier ways to integrate workflow in packages along with some good examples, better leverage of components like the content repository by providing a better Tcl API, etc).
Lots and lots of work to be done.
Oh joy!
