Thread: Users comments don't migrate to docs for new version?
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
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"
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
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
On 6/6/07, Magnus Hagander <magnus@hagander.net> wrote: > Alvaro Herrera wrote: > > 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 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
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
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)
On 6/6/07, Magnus Hagander <magnus@hagander.net> wrote: > Alvaro Herrera wrote: > > 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 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
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
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
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)
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
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)