Of course, its also worth pointing out that as newbies are the ones who generally press harder for more documentation, then perhaps we should make it easy for them to add to it, as they find holes!
Also, one of the problems with documentation is that it gets easily out of sync with development. Its also not always a good reference (whereas the code always is)...
This is hardly unique to the OpenACS. Virtually all OS projects suffer from it...
As for the comments on the OpenACS being difficult... hmmm.. has he ever tried getting JBoss/Tomcat going I wonder....?
The reality is that this is human nature. Many of the contributors here (I daresay) have to do docs as part of their job. I cn easily understand why they may be reluctant to do it for volunteer projects. After all documentation is not one of the most inspiring tasks to do is it.
Thats not to say we shouldn't bother, but I suspect we need to come up with a different/better way of documenting that works with, rather than against human nature.
Or... we end up with a dreadful scheme such a Jboss.org has.. i.e. you have to *pay* for the documents!... Yurrck....
Any suggestions?
I think the first thing we could do is remove/hide/defer to a less visible place, much of that 'orrible design documentation that lingers from 4.2...
Whilst its good tech doc, unless you're pretty clued up anyway its dry and complex in the extreme.
Perhaps a simple re-organisation of documentation already there (there is quite a bit) is in order first. Perhaps grouping things according to reader, rather than by-package/code..
I.e. a simpler, newbie user guide, a more details developer guide and a full on system guide... each containing the same stuff, just with varying levels of detail.
Most of the things people ask for in docs, are often there... they're just not that easy to find...
