Subject: Users comments don't migrate to docs for new version?

From: "Nikolay Samokhvalov" <[email-masked]>
Date: Wed, 6 Jun 2007 20:10:24 +0400

I've just found (via google...) useful (for me) comments:
http://www.postgresql.org/docs/8.0/interactive/sql-createaggregate.html
-- I mean users comments under primary contents of the page.

These comments were written for 8.0, but are useful for the current
versions too. What we have is the situation that reading docs for 8.2
people don't see these comments -- so this potentially useful
information is lost. So, in this implementation the idea of comments
for docs becomes weak in general.

In some other OSS projects comments for docs are used intensively and
hold a lot of useful information for many people. The good example
here is PHP docs -- sometimes comments are much more useful and much
more important then the main contents itself!

I understand that comments migration and maintenance might be a hard
task, because some comments may be really out-dated... Maybe simple
notice like "this comment was created for pg 8.0 docs" would help.

-- 
Best regards,
Nikolay

---

From: Alvaro Herrera <[email-masked]>
Date: Wed, 6 Jun 2007 12:40:29 -0400

> for docs becomes weak in general.

The thing to do in these cases is to move the useful info from the user
comments into the main doc text.

-- 
Alvaro Herrera                        http://www.advogato.org/person/alvherre
"La victoria es para quien se atreve a estar solo"

---

From: Magnus Hagander <[email-masked]>
Date: Wed, 06 Jun 2007 21:18:29 +0200

> comments into the main doc text.

Yeah, that's the idea. Tom often goes through the comments and puts
stuff into the docs. But I'm sure there are a *lot* of other people who
could help with that as well - read comments, figure out of they make
sense, and submit a docs patch for the next version!

//Magnus

---

From: Alvaro Herrera <[email-masked]>
Date: Wed, 6 Jun 2007 15:40:15 -0400

> sense, and submit a docs patch for the next version!

Other people!?!?!?  What are you thinking -- why would _anyone_ spend
any effort in this, if Tom can make all the work for us???  No one else
needs to bother!!!  Surely Tom is the only person on earth who knows how
to write proper english anyway.

-- 
Alvaro Herrera                                http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

---

From: "Nikolay Samokhvalov" <[email-masked]>
Date: Thu, 7 Jun 2007 10:10:19 +0400

> sense, and submit a docs patch for the next version!

But I suppose there are some cases when it's not possible to move the
comment to the main text -- e.g. if the comment concerns too narrow
area, is very specific and is useful not for all people (but still
useful for some!).

Moreover, moving good comments to the main text makes the text bloated
-- what if we have 10 examples of using function aaa() and all of them
are illustrations for different areas? We (ok, sorry, Tom because only
he knows English) will choose only 1 of them to avoid bloating of the
main text, even if all 10 use cases has some specific features...

Users comment collection is a good thing! Ask any PHP developer --
many of them will say that user comments that the main manual has are
something like cookbooks -- lots of useful 	recipes.

I could help with (yeah, not with reworking comments -- I do not know
English well :-) ) creating a simple patch that adds a notice "this
comment was originally created for version 8.0" and maybe something
else in this direction -- these my thoughts are not fresh, I always
lacked good user comments... BTW, then we would add some
marking/rating system to the comments to allow other users see what
comment is really useful.

-- 
Best regards,
Nikolay

---

From: David Fetter <[email-masked]>
Date: Thu, 7 Jun 2007 10:06:51 -0700

On Wed, Jun 06, 2007 at 09:18:29PM +0200, Magnus Hagander wrote:
> >> These comments were written for 8.0, but are useful for the
> >> current versions too.  What we have is the situation that reading
> >> docs for 8.2 people don't see these comments -- so this
> >> potentially useful information is lost.  So, in this
> >> implementation the idea of comments for docs becomes weak in
> >> general.
> > 
> > The thing to do in these cases is to move the useful info from the
> > user comments into the main doc text.
> 
> stuff into the docs.  But I'm sure there are a *lot* of other people
> who could help with that as well - read comments, figure out of they
> make sense, and submit a docs patch for the next version!

It occurs to me that we could encourage this by emphasizing on the
interactive docs that user comments are not carried forward
automatically and pointing to a place where people can learn how to
submit such patches if they so desire.

Here is the wording I'd propose to replace the paragraph after "Add Comment":

Please use this form to add your own comments regarding your
experience with particular features of PostgreSQL, clarifications of
the documentation, or hints for other users.  These comments are
not automatically carried into future versions of the documentation.
If you believe your change should carry forward, please consider <a
href="http://www.postgresql.org/docs/current/static/docguide.html">patching
the document source SGML</a> and sending those patches to <a
href="mailto:[email-masked]">psql-docs</a> for inclusion in
the official documentation.  This is a way to participate more in the
PostgreSQL project.

This is not a support forum, and your IP address will be logged.  If
you have a question or need help, please see the <a
href=http://www.postgresql.org/docs/faq/>FAQ</a>, try a mailing <a
href="http://www.postgresql.org/community/lists/">list</a>, or join us
on <a irc://irc.freenode.net/postgresql>IRC</a>.

Submissions containing URLs or other keywords commonly found in spam
comments may be silently discarded.  Please contact the <a
href="mailto:[email-masked]">webmaster</a> if you think this
is happening to you in error.

Cheers,
David.
-- 
David Fetter <[email-masked]> http://fetter.org/
phone: +1 415 235 3778        AIM: dfetter666
                              Skype: davidfetter

Remember to vote!
Consider donating to PostgreSQL: http://www.postgresql.org/about/donate

---

From: "Nikolay Samokhvalov" <[email-masked]>
Date: Fri, 8 Jun 2007 01:18:58 +0400

--
Best regards,
Nikolay

---

From: Alvaro Herrera <[email-masked]>
Date: Thu, 7 Jun 2007 18:33:35 -0400

Nikolay Samokhvalov wrote:

> English well :-) )

You could certainly rework comments into changes to the main text and
send them to the pgsql-docs list.  If there are problems with the
grammar, somebody will correct it.  Or maybe they won't, but it doesn't
matter, because the good thing is that the new text will be there.  A
piece of text with a minor grammatical error is better than no text at
all.

-- 
Alvaro Herrera                        http://www.advogato.org/person/alvherre
"We're here to devour each other alive"            (Hobbes)

---

From: "Andrej Ricnik-Bay" <[email-masked]>
Date: Fri, 8 Jun 2007 11:24:09 +1200

> piece of text with a minor grammatical error is better than no text at
Amen to that :}  (at least if it's not completely misleading).

---

From: Kevin Hunter <[email-masked]>
Date: Fri, 8 Jun 2007 07:56:33 -0400

> main text, even if all 10 use cases has some specific features...

Hrm.  If they're still good comments, what about including a  
hyperlink to a pop-up or separate page with some specific information  
about that particular point?  ("There is more <a  
href='popup'>discussion on the many uses of the function aaa()</a>")   
Bloat for the main documentation could still avoided, but if read on- 
line (as the docs are meant to be read?) then access to other's  
wisdom need not lost/weeded out.

> comment was originally created for version 8.0" and maybe something

Although, short of above, perhaps this'd be an easier en masse solution?

> BTW, then we would add some marking/rating system to the comments  
> to allow other users see what comment is really useful.

Kind of like digg or something?  Where the higher-rated float to the  
top?

Kevin

---

From: Oleg Bartunov <[email-masked]>
Date: Fri, 8 Jun 2007 16:41:48 +0400 (MSD)

The possible solution would be a forum with specific page as 
an originated message and users comments as a thread messages.
We use this approach for many years.

Oleg
On Fri, 8 Jun 2007, Kevin Hunter wrote:

> Hrm.  If they're still good comments, what about including a hyperlink to a 
> pop-up or separate page with some specific information about that particular 
> point?  ("There is more <a href='popup'>discussion on the many uses of the 
> function aaa()</a>")  Bloat for the main documentation could still avoided, 
> but if read on-line (as the docs are meant to be read?) then access to 
> other's wisdom need not lost/weeded out.
>
>> BTW, then we would add some marking/rating system to the comments to allow 
>> other users see what comment is really useful.
>
> Kind of like digg or something?  Where the higher-rated float to the top?
>
> Kevin
>
> ---------------------------(end of broadcast)---------------------------
> TIP 1: if posting/reading through Usenet, please send an appropriate
>     subscribe-nomail command to [email-masked] so that your
>     message can get through to the mailing list cleanly

 	Regards,
 		Oleg
_____________________________________________________________
Oleg Bartunov, Research Scientist, Head of AstroNet (www.astronet.ru),
Sternberg Astronomical Institute, Moscow University, Russia
Internet: [email-masked], http://www.sai.msu.su/~megera/
phone: +007(495)939-16-83, +007(495)939-23-83

---

From: Jim Nasby <[email-masked]>
Date: Wed, 11 Jul 2007 12:49:44 -0500

On Jun 6, 2007, at 2:18 PM, Magnus Hagander wrote:
> who

It would be substantially easier to do that if there was an index  
page that listed all comments.
--
Jim Nasby                                            [email-masked]
EnterpriseDB      http://enterprisedb.com      512.569.9461 (cell)

---

From: Magnus Hagander <[email-masked]>
Date: Wed, 11 Jul 2007 19:51:45 +0200

Jim Nasby wrote:
> It would be substantially easier to do that if there was an index page
> that listed all comments.

There is supposed to be one in the admin interface. But it seems I broke
that with the latest update :-)

Are you volunteering for doing some work on it? If so, I'm going to
increase the priority of fixing that :-)

//Magnus

---

From: Jim Nasby <[email-masked]>
Date: Fri, 13 Jul 2007 01:03:30 -0500

> increase the priority of fixing that :-)

Not at this point, but perhaps later.
--
Jim Nasby                                            [email-masked]
EnterpriseDB      http://enterprisedb.com      512.569.9461 (cell)