One might argue (as XP does) that if you can't read/understand source code, you have no business working with it at a technical level.
That is certainly a valid point, but considering the complexity of OpenASC 4.6 I think telling newbies to go read the source code would be a bit extreme. I think documentation explaining the basic steps of installation and simple package development is required. Joel Aufrecht's new docs are great in that respect.
Apart from that I agree with you completely. Readable code is a better solution than outdated docs. Also good tools like the API documentation are essential - means of taking source code and turning it into documentation. OpenACS is too complex to simply read the source code and I'm not even sure that all functionality is represented in the packages (I was looking for ad_form syntax for checkboxes the other day without luck).
