Forum OpenACS Development: Why is aD documentation so bad?

Posted by Henry Minsky on
The state of the documentation for the ACS continually leaves
me feeling very unsatisfied. When I look at the documentation
set for something like Postgres, I get a very warm fuzzy feeling,
because I know I can find out what I need to know: The user's manual
says how to use the system, the reference manual contains
concise descriptions of the  API and example usage, the programmers
guide says how to
program extensions.

The ACS module documentation are heavy on the requirements and design
documents, which are nice for a few people once in awhile, but most
people want to know how to *use* the module, and there is generally
no users manual with even important core modules, and
the API is thinly documented by comments in ad_proc declarations.
These are uniformly too brief and contain
virtually no example code (except maybe for the ad_page_contract

When a module is small and stand alone, this isn't such an issue, but
it is really crippling for something like acs-messaging,or general-
comments, which is supposed to be shared infrastructure among many
modules, and thus it proper and expected behavior
needs to be understandable and used by many developers.

Constructive things to do in the future would be to

Look at
good examples of documentation, and try to emulate them.

If you
write an ad_proc, add examples to illustrate the calling conventions
or behavior.

While people are porting the main modules, it is probably a good
opportunity to try to write at least some notes for a users-guide
where there is none, and where it is not obvious how to use the
module's capabilities. And it wouldn't hurt to touch up the ad_proc
documentation if you are in a function and have discovered something
important about how to use it that other people should know.

Just wanted to get this off my chest ...

Posted by David Eison on
One thing I find fascinating about the aD documentation is that it is easy to learn and emulate, so that systems developed on top of the aD infrastructure can easily have some documentation.  So, the initial documentation may not be as nice & useful as the books you can read about other systems, but I think the documentation of the actual product you end up building is far better than a product developed with another system where no documentation is done on the customizations/extensions/new modules.  I hope that if overall documentation is improved, this ease of emulation won't be lost (i.e. improvements would be via better ad_proc comments or some other easily emulated & maintained system instead of glossy books)
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.

Posted by Stephen . on
Writing documentation; requirements, design and user documents is hard. I don't expect this to change any time soon.

However, proc documentation is inceredibly easy to write, hard to get out of sync, and serves the main ACS audience at the moment, programmers, very well.

Note when porting: gratuitous use of the Tcl namespace feature has broken proc documentation for what little exists. Be careful where you eval ad_proc.

Posted by Steve Woodcock on
The OpenACS version of ad_proc handles namespaces correctly, or at least it should do.
Posted by Michael Feldstein on
As far as I can tell, the ACS has never really had what I would call
"user" docs. Most of the time when I'm puzzling through some
complex module or other with a gosh-awful interface (like
Intranet, for example), I'll find plenty of snippets of SQL (gee,
thanks a lot) but absolutely no explanation of how to use the
darned thing. Even a supposedly simple module like
general-comments (or is it static-comments? How many
modules does it take to get this damned thing done?) is
impossible to figure out unless you can actually read the code.

Part of the problem is that Philip never clearly distinguished
between admins and programmers or, for that matter, users. I
always found it incredibly annoying that some modules in 3.x
display the code used to carry out an operation as an FYI.

At any rate, I volunteer to help write user-level documentation,
and I also volunteer to recruit others to help write it. You don't
need programmers for this; in fact, being a programmer might
just get in your way. You just need good writers who have access
to an installed system and are willing to play with it.

7: User level docs (response to 1)
Posted by Walter McGinnis on

If I remember correctly, at one point there was a "help" module for ACS which provided a link on user pages to user level help docs. The idea being that programmers/admins/those in the know would write help docs for users as they were writing new modules. Anyway, not sure what happenened to that initiative, but I think it had a the kernel of the right idea; providing a link to the relevant user level docs from specific user pages. Maybe we can standardize on this.

Oh yeah, I rewrote the glossary module for ACS 4x last fall. It might be usefull for documentation if ported.

Posted by Michael Feldstein on
I agree, Walter; standard and ubiquitous context-sensitive help
module is more important than ever, now that the system is
getting so complex.
Posted by Michael Feldstein on
BTW, Walter, are you planning on porting that glossary module?
It would be very useful for OpenACES.
Posted by Pascal Scheffers on
Porting of the glossary module has been assigned to me (but I'm not very proprietary and haven't started on it yet - Walter can do it if he wants to ;-).

Walter, is the glossary module on the aD site the version you wrote? If so I have a question :)

In this thread, I asked something about the main glossaries table and Steve Woodcock gave me a troubling answer: That looks like a mistake to me. Am I misunderstanding Oracle objects or is he? (or is it something else all together)

Posted by Walter McGinnis on

I think you are confusing ACS 4's concept of objects with Oracle's built in object extensions. Steve Woodcock is correct that the data model is relational with some PL/SQL. It does however use acs_objects to tie into the rest of the ACS 4's data modelling conventions which are somewhat object based.

Refer back to the thread you linked to for a response to the "mistake" aspect of what Steve was referring to.

I'll be happy to give pointers on the porting of the Glossary Package, but I'm going to be busy with the Photo Album port as my main project.

I believe Dennis Gregorovic did some work on the Glossary Package after I left aD, but I think it was mainly incorporating bug fixes. So yes, go ahead and use the latest version from aD. It is alpha software and there are several things that need to be fixed. Make sure to read the comments in the code. I was pretty good about outlining potential problems.

Posted by Dennis Gregorovic on
Yes, I did do a bit of touch-up on the glossary module, although it's actually is pretty good shape for alpha code, and the docs are thorough.  If you have questions when porting it just post here and Walter or I can chip in.