Lars ... I agree that we really need a package developer's guide such as you describe. I have two problems, though. You can probably guess the first:
- Resource - who has time to do it?
A document properly covering the items you discuss, complete with well-commented examples and toolkit references, is not a trivial piece of work. That's not a bad outline for about half of an OpenACS O'Reilly book. It could only be done with someone who has intimate knowledge of how the toolkit works. There may be as many as a dozen people in our community who have that knowledge but I doubt if there's more.
If our community were more robust financially, it would be a good project to fund, pay someone for a solid month or so to put together a really good document.
Perhaps I'm overestimating the effort required. Am I? What do you think? Any ideas as to how we can get something like this written short of paying for it?
- If we implement some or all of our labor-saving ideas in 4.7, the contents of such a document would be obsolete before it was completed unless the writing of it were put off until these new tools are written. This is a minor thing, IMO.
Roberto ... when I suggest a "document blitz month" you can be assured that it would come complete with arm-twisting, begging, and personal cajoling from me. And of course yourself and I assume other leaders in the community. I would also, of course, commit to working on documentation myself.
If we just lock down the tree and implement a moratorium on code changes we may just find that no code gets written and, damn!, neither does any documentation.
I agree entirely with you in spirit, though, we need to do something to tackle the documentation problem, and getting a bunch of us involved working on it at once is a good idea.
