pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedAnnotatable on-line documentation
5+ messages / 4 participants
[nested] [flat]
* Annotatable on-line documentation
@ 2001-02-16 17:40 Richard <poboxcanada@yahoo.com>
0 siblings, 2 replies; 5+ messages in thread
From: Richard @ 2001-02-16 17:40 UTC (permalink / raw)
To: pgsql-general@postgresql.org
(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/
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Annotatable on-line documentation
@ 2001-02-16 20:28 Dave Cramer <Dave@micro-automation.net>
parent: Richard <poboxcanada@yahoo.com>
1 sibling, 0 replies; 5+ messages in thread
From: Dave Cramer @ 2001-02-16 20:28 UTC (permalink / raw)
To: Richard <poboxcanada@yahoo.com>; pgsql-general@postgresql.org
You should have a look at the wiki stuff
http://c2.com/cgi/wiki?WikiWikiWeb
Dave
----- Original Message -----
From: "Richard" <poboxcanada@yahoo.com>
To: <pgsql-general@postgresql.org>
Sent: Friday, February 16, 2001 12:40 PM
Subject: [GENERAL] 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/
>
>
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Annotatable on-line documentation
@ 2001-02-16 20:38 Peter Eisentraut <peter_e@gmx.net>
parent: Richard <poboxcanada@yahoo.com>
1 sibling, 1 reply; 5+ messages in thread
From: Peter Eisentraut @ 2001-02-16 20:38 UTC (permalink / raw)
To: Richard <poboxcanada@yahoo.com>; +Cc: pgsql-general@postgresql.org
Richard writes:
> 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?
My concerns are mostly that that kind of thing would be abused as a
discussion forum, the quality of the comments is quite low on average, and
the added efforts to weed out the posts on a regular basis seem
prohibite.
I don't see any particular advantage coming from this that couldn't be
achieved in another way.
> A pilot project may be enlightening. Anyone have
> experience with setting up/maintaining annotatable
> on-line documentation?
What I've seen at PHP and MySQL was enlightening enough for me. :-(
--
Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Annotatable on-line documentation
@ 2001-02-17 14:30 Martijn van Oosterhout <kleptog@svana.org>
parent: Peter Eisentraut <peter_e@gmx.net>
0 siblings, 1 reply; 5+ messages in thread
From: Martijn van Oosterhout @ 2001-02-17 14:30 UTC (permalink / raw)
To: Peter Eisentraut <peter_e@gmx.net>; +Cc: Richard <poboxcanada@yahoo.com>; pgsql-general@postgresql.org
Peter Eisentraut wrote:
>
> Richard writes:
>
> > 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?
>
> My concerns are mostly that that kind of thing would be abused as a
> discussion forum, the quality of the comments is quite low on average, and
> the added efforts to weed out the posts on a regular basis seem
> prohibite.
>
> I don't see any particular advantage coming from this that couldn't be
> achieved in another way.
Well, one thing would be is that it would make it easier for other
people to submit changes to a particular page on the docs. You can just
go there and submit a change. Sending a patch much harder.
Maybe, as someone else suggested, a moderated one. That would stop the
discussion problem.
--
Martijn van Oosterhout <kleptog@cupid.suninternet.com>
http://cupid.suninternet.com/~kleptog/
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Annotatable on-line documentation
@ 2001-02-17 14:50 Peter Eisentraut <peter_e@gmx.net>
parent: Martijn van Oosterhout <kleptog@svana.org>
0 siblings, 0 replies; 5+ messages in thread
From: Peter Eisentraut @ 2001-02-17 14:50 UTC (permalink / raw)
To: Martijn van Oosterhout <kleptog@svana.org>; +Cc: Richard <poboxcanada@yahoo.com>; pgsql-general@postgresql.org
Martijn van Oosterhout writes:
> Well, one thing would be is that it would make it easier for other
> people to submit changes to a particular page on the docs. You can just
> go there and submit a change. Sending a patch much harder.
The policy for documentation submissions has always been "Give us words
and we'll do the rest."
--
Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2001-02-17 14:50 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2001-02-16 17:40 Annotatable on-line documentation Richard <poboxcanada@yahoo.com>
2001-02-16 20:28 ` Dave Cramer <Dave@micro-automation.net>
2001-02-16 20:38 ` Peter Eisentraut <peter_e@gmx.net>
2001-02-17 14:30 ` Martijn van Oosterhout <kleptog@svana.org>
2001-02-17 14:50 ` Peter Eisentraut <peter_e@gmx.net>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox