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

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

From
"Nikolay Samokhvalov"
Date:
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

Re: [pgsql-www] Users comments don't migrate to docs for new version?

From
Alvaro Herrera
Date:
Nikolay Samokhvalov wrote:
> 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.

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"

Re: [pgsql-www] Users comments don't migrate to docs for new version?

From
Magnus Hagander
Date:
Alvaro Herrera wrote:
> Nikolay Samokhvalov wrote:
>> 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.
>
> The thing to do in these cases is to move the useful info from the user
> 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

Re: [pgsql-www] Users comments don't migrate to docs for new version?

From
Alvaro Herrera
Date:
Magnus Hagander wrote:
> Alvaro Herrera wrote:
> > Nikolay Samokhvalov wrote:
> >> 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.
> >
> > The thing to do in these cases is to move the useful info from the user
> > 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!

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

Re: [pgsql-www] Users comments don't migrate to docs for new version?

From
David Fetter
Date:
On Wed, Jun 06, 2007 at 09:18:29PM +0200, Magnus Hagander wrote:
> Alvaro Herrera wrote:
> > Nikolay Samokhvalov wrote:
> >> 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.
> >
> > The thing to do in these cases is to move the useful info from the
> > user 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!

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:pgsql-docs@postgresql.org">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:webmaster@postgresql.org">webmaster</a> if you think this
is happening to you in error.

Cheers,
David.
--
David Fetter <david@fetter.org> 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

Re: [pgsql-www] Users comments don't migrate to docs for new version?

From
Alvaro Herrera
Date:
Nikolay Samokhvalov wrote:

> I could help with (yeah, not with reworking comments -- I do not know
> 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)

Re: [pgsql-www] Users comments don't migrate to docs for new version?

From
"Andrej Ricnik-Bay"
Date:
On 6/8/07, Alvaro Herrera <alvherre@commandprompt.com> wrote:

> 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.
Amen to that :}  (at least if it's not completely misleading).

Re: [pgsql-www] Users comments don't migrate to docs for new version?

From
Oleg Bartunov
Date:
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:

> At 5:18p -0400 on 07 Jun 2007, Nikolay Samokhvalov wrote:
>
>> 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...
>
> 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.
>
>> 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
>
> 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
>
> ---------------------------(end of broadcast)---------------------------
> TIP 1: if posting/reading through Usenet, please send an appropriate
>     subscribe-nomail command to majordomo@postgresql.org 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: oleg@sai.msu.su, http://www.sai.msu.su/~megera/
phone: +007(495)939-16-83, +007(495)939-23-83

Re: [pgsql-www] Users comments don't migrate to docs for new version?

From
Jim Nasby
Date:
On Jun 6, 2007, at 2:18 PM, Magnus Hagander wrote:
> Alvaro Herrera wrote:
>> Nikolay Samokhvalov wrote:
>>> 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.
>>
>> The thing to do in these cases is to move the useful info from the
>> user
>> 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!

It would be substantially easier to do that if there was an index
page that listed all comments.
--
Jim Nasby                                            jim@nasby.net
EnterpriseDB      http://enterprisedb.com      512.569.9461 (cell)



Re: [pgsql-www] Users comments don't migrate to docs for new version?

From
Magnus Hagander
Date:
Jim Nasby wrote:
> On Jun 6, 2007, at 2:18 PM, Magnus Hagander wrote:
>> Alvaro Herrera wrote:
>>> Nikolay Samokhvalov wrote:
>>>> 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.
>>>
>>> The thing to do in these cases is to move the useful info from the user
>>> 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!
>
> 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


Re: [pgsql-www] Users comments don't migrate to docs for new version?

From
Jim Nasby
Date:
On Jul 11, 2007, at 12:51 PM, Magnus Hagander 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 :-)

Not at this point, but perhaps later.
--
Jim Nasby                                            jim@nasby.net
EnterpriseDB      http://enterprisedb.com      512.569.9461 (cell)