Forum OpenACS Q&A: How about an Annotated Manual or interactive documentation?
The purpose would not be for people to ask questions, but would instead be for people to contribute more info to the docs in a rapid manner and make it easier for the writers/ maintainers to know what is missing or needs clarification.
After a comment is read, and the docs changed (if needed), then the
comment should be deleted.
The SDM is just not easy enough when it comes to making suggestions
from the floor for something like the documentation; it is great for code
changes, bugs, and feature requests.
Give people good tools, and give several people (if they are willing to step up) the job of reviewing the comments and improving the docs. I think it could do wonders.
Sam
I said:
> ...software requirements... PostgreSQL + ??
Vince Vielhaber [vev@michvhf.com] said:
It's set up on apache w/ PHP 4.0.x and PostgreSQL.
I wrote a script that read each html doc file and encoded it so
it would go into the database (escaped apostrophes, etc) and
stored that along with a language tag, page number, reference
number, filename and a couple of other things. The php script
that does the work (index.php) does a global replace upon display
(not on storing it in the database) that puts:
http://www.postgresql.org/idocs/index.php?
in front of all urls so anything displayed or clicked on will go
thru index.php. if it's a non-local url a redirect is made to
the
raw url. The search simply does an ILIKE search, after removing
any malicious characters (there are morons everywhere that just
live to break things, one even had the gonads to send me email
about it!) so I only allow a-z A-Z 0-9 and spaces, all else is
converted to a space. The user comments are converted before
being
stored to their printable forms (a PHP function does this) and
that's about it. The source isn't available just yet but I want
it
to be in the not too distant future - but don't wait on it :)
Vince.
He also said:
>There aren't really any requirements to the interactive docs beyond
that
>they're not supposed to be used as a support forum. Before I
delete any
>of them I look at them long and hard, quite often something that appears
>to be a support question (and may very well be) will be an excellent
way
>of saying the docs are omitting something fairly obvious. On
the other
>hand the "I don't know how to do this" type of questions are deleted
>without giving it a second thought. Source code and config examples,
>corrections, corrections to the source code or config examples, additions
>of explanations, and other stuff like that is mainly what it's about.
>If you take a look at the interactive docs that the PHP folks use
>(www.php.net) you'll get an idea since that's what I modeled it after
>somewhat.
