Forum OpenACS Development: Why is aD documentation so bad?
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
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
good examples of documentation, and try to emulate them.
write an ad_proc, add examples to illustrate the calling conventions
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 ...
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 openacs.org 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 https://openacs.org/docs/yourmodulecouldbehereaskmehow/userguide 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.
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.
"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.
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.
module is more important than ever, now that the system is
getting so complex.
It would be very useful for OpenACES.
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)
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.