Forum OpenACS Development: Response to Why is aD documentation so bad?

Posted by Jerry Asher on
JDE within Emacs has a generate documentation command (on the menu too.) It will walk through your java file and create prototyping javadoc for every class and method. I find that helps get me over my activation energy barrier.

I think part of the problem is that documentation is hard: as you write it, you never really know what the users will need, or what parts they will find confusing and requiring more explanation. Add to that the time consuming nature of the task and how quickly it gets old and needs to be revised.

I would love to see enhanced to support collaborative documentation of the modules. (I'd give someone's left nut for an ACS WIKI). It would be great if folks could come to for the userguide, and even more wonderful if that userguide could be collaboratively edited or at the least had general comments turned on. Same with /docs/yourmoduletoo/design, api, datamodel and admin.