Forum OpenACS Q&A: Response to Package Documentation

Collapse
Posted by Jon Griffin on
The content not the docbook requirement was a failure.

Almost all of the docs were written by the developer for the developer and (as has been alluded to many times) very little meat either for 3rd party developers or end users.

Example code is not relevant (if it exists at all), and the use cases while interesting don't help many people.

I guess what I am getting at is the fact that documentation should have how to use the package, how to extend the package, as well as the reasons for the package existing.

Even though there is an api browser, each package should say what procs are defined (both db and tcl) and also document the complete data model. Then you could see if another package does what you want or has written a function you need, and so on and so forth.

Just my thoughts, but I think there should be a defined standard of minimal requirements for documentation and AD's wasn't good.