Annotatable on-line documentation

(This was: "Re: [GENERAL] Re: PostgreSQL vs Oracle vs
DB2 vs MySQL - Which should I use?", but I think a new
thread has spun off...)

[Tom Lane said ...]
> I agree we need to work harder on making answers
findable
> outside the mailing lists.  Improving the docs,
making the mail archives
> more easily searchable, etc etc.  I dunno if an
"annotated manual" would
> help --- I've never used one --- but if people want
to try one, it can't hurt.

[... to which Bruce Momjian added ...]
> I will say that the FAQ and my book have visibly
reduced the number of
> questions.  When I put something on the FAQ, the
questions about that
> topic just magically go away.

I have not used an annotated document either.
However, I could see such a beast being used in the
development of the documentation in a way that is not
dissimilar to the development of the product itself.
That is, I see an annotatable set of documentation as
similar in nature to the developmental version of the
product.  After some period of development, some lucky
editor(s) would fold the annotations into the document
proper, periodically releasing the "stable" version of
the docs.

Would this lighten the work load on the folk that are
currently maintaining the docs?  Would it lighten the
work load for the core developers?  Would it stimulate
the development of richer documetation?  Would it draw
some of the load off the mailing lists?

A pilot project may be enlightening.  Anyone have
experience with setting up/maintaining annotatable
on-line documentation?

Cheers,
Richard Blackwell
Programmer/Analyst
Simon Fraser University
Burnaby, BC Canada



__________________________________________________
Do You Yahoo!?
Get personalized email addresses from Yahoo! Mail - only $35
a year!  http://personal.mail.yahoo.com/