Forum OpenACS Q&A: Package Documentation

I'm browsing the download secion and i note that the different
packages for OACS 4 are lacking any documentation what-so-ever most
of the packages don't even have a note that hints at what they do
(granted it is fairly obvious from the package name usually). As a
fairly new member of the OACS it would save me a great deal of time
in the project planning stage if i knew what the package did! The bug
tracking system, on the other hand, is awsome.

Any comments?

Actually most of the package do currently have documentation, the same documentation provided by aD when ACS 4.2 was released.

You need to point your browser locally at packages/foo-package/www/doc to find them.  The documentation tends to be at the requirements-design level rather than user level, but they should at least help you understand what a package does and how it does it.

As Roberto says we're making progress in our own documentation efforts, which will build on documents inherited from aD.  And the more help we get the better the documents will be!

Jon,

I modified and did some retouching and updating to the Documentation guide that aD had made, and that's what we've been using. We inherited a lot of Docbook XML documentation and we couldn't just change all that, so that's the format we are using, at least for the core docs.

What I noticed was the the tools for dealing with Docbook SGML are more mature and easier to work with, but since everything we had was in XML, we had to keep it.

What I'm seeing now are packages where only HTML documentation is being done only in HTML, and we're in for big trouble if we start fragmenting things like that.

In one hand I understand that it's an added burden for someone creating a package to learn and mess with Docbook XML, and all the tools involved. But on the other hand, we'll have to come up with a standard at some point. The advantages of Docbook are indexing, output to several formats (SGML makes this easier, with XML it's trickier) including PDF, easy linking, etc.

When you say that "AD's format was a dismal failure and existed only to say they were documented", are you referring to Docbook? Or to the documentation templates they created?

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.

I will volunteer to put together a spec for public scrutiny.

I can base it on what AD started and go from there. I just didn't want to step on anyones toes, if this was already in the works.

I will have a preliminary spec done by Tuesday if we are in agreeance.

Jon, that'd be great. Let me know if I can be of assistance.

Well I am a day late, but I have a document on my server with some initial thoughts as to a documentation standard.

I took my thoughts as well as some ideas from Linux Doc Project and GNU. It is a work in progress now and I am looking for comments, omissions etc.

The doc is at http://jongriffin.com/static/openacs/OpenACS-documentation

May I suggest using bug-tracker as the example package? I need to add Oracle support and documentation, but aside from those grave ommissions, I've tried to make it a model of OpenACS package development.