Forum OpenACS Development: Response to Why is aD documentation so bad?

Collapse
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.