I read the entire thread and the question that keeps popping into my mind is why don't we all go over to to
https://openacs.org/doc/openacs-4/ and start adding user comments until such a point as there are enough comments there to revise the documentation?
The tool is already in place for us to document every API and make the OACS documentation all that we want it to be. To quote Nike, "just do it."
