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
docs).
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 ...
