Forum OpenACS Q&A: How about an Annotated Manual or interactive documentation?

Posted by Sam Snow on
I know this has been mentioned before (see ), but why not pull together a copy of the manual that comments can be added to so that people can quickly add info to. now has one, written by Vince Vielhaber []. I'll post what he said about them at the bottom of this message. PHP also has them, and their source is downloadable from them.

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.


I said:
> requirements... PostgreSQL + ??

Vince Vielhaber [] 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:

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 :)


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
>( you'll get an idea since that's what I modeled it after