Обсуждение: Re: [GENERAL] COPY command documentation
On Thu, Mar 23, 2006 at 07:00:13PM +0100, Jim Nasby wrote: > On Mar 23, 2006, at 4:08 PM, Oisin Glynn wrote: > > >I just discovered that the comments from 8.0 had the answer I was > >looking for but these comments are not in the 8.1 docs. Should the > >comments be rolled forward as new versions are created? Or if valid > >comments added to the docs themselves? > > > >http://www.postgresql.org/docs/8.1/interactive/sql-copy.html > > > >http://www.postgresql.org/docs/8.0/interactive/sql-copy.html > > No, comments don't roll forward. ...and it's unlikely that they will, now or later, without somebody whose whole job is to monitor those comments and make patches. I'd like to make a Modest Proposalâ¢: Let's take down the interactive documents and, in their place, put up a request that doc patches be sent to -docs. What say? Cheers, D -- David Fetter <david@fetter.org> http://fetter.org/ phone: +1 415 235 3778 AIM: dfetter666 Skype: davidfetter Remember to vote!
On Thu, 2006-03-23 at 14:12, David Fetter wrote: > On Thu, Mar 23, 2006 at 07:00:13PM +0100, Jim Nasby wrote: > > On Mar 23, 2006, at 4:08 PM, Oisin Glynn wrote: > > > > >I just discovered that the comments from 8.0 had the answer I was > > >looking for but these comments are not in the 8.1 docs. Should the > > >comments be rolled forward as new versions are created? Or if valid > > >comments added to the docs themselves? > > > > > >http://www.postgresql.org/docs/8.1/interactive/sql-copy.html > > > > > >http://www.postgresql.org/docs/8.0/interactive/sql-copy.html > > > > No, comments don't roll forward. > > ...and it's unlikely that they will, now or later, without somebody > whose whole job is to monitor those comments and make patches. > > I'd like to make a Modest Proposalâ„¢: Let's take down the interactive > documents and, in their place, put up a request that doc patches be > sent to -docs. Heck, why not a form that does it for somebody, takes their email address, and possibly even enrolls them in the -docs newsgroup. It can't be that hard to code up.
On Thursday 23 March 2006 15:12, David Fetter wrote: > On Thu, Mar 23, 2006 at 07:00:13PM +0100, Jim Nasby wrote: > > On Mar 23, 2006, at 4:08 PM, Oisin Glynn wrote: > > >I just discovered that the comments from 8.0 had the answer I was > > >looking for but these comments are not in the 8.1 docs. Should the > > >comments be rolled forward as new versions are created? Or if valid > > >comments added to the docs themselves? > > > > > >http://www.postgresql.org/docs/8.1/interactive/sql-copy.html > > > > > >http://www.postgresql.org/docs/8.0/interactive/sql-copy.html > > > > No, comments don't roll forward. > The general consensus is that comments should not automatically roll forward, since many comments are version specific. People are of course free to repost comments if they find them appropriate. > ...and it's unlikely that they will, now or later, without somebody > whose whole job is to monitor those comments and make patches. > Well, we do make some attempt at rolling comments into the docs where appropriate, but we could certainly use more dedicated contributors in that area. > I'd like to make a Modest Proposalâ¢: Let's take down the interactive > documents and, in their place, put up a request that doc patches be > sent to -docs. > > What say? > I'd say you're anti-interactive comments :-) More importantly, people just aren't going to to write patches for doc additions... the overhead is several orders of magnitudes greater than filling at a web form... so getting rid of the comments is sure to lose any gains that we receive. What I have tried to garner support for in the past was to either direct those submission to this group for approval/rejection, which would make the folks generally interested in docs directly involved in the process. The other option would be to mail approved doc comments to this group so that someone could work them up into doc patches if applicable. That really is a factor, most of the comments would need to be reworded to be added into the docs proper. In the past these ideas were rejected as either off-topic or that it would turn this list into a high traffic list... if peoples opinions have changed, it could be arranged. -- Robert Treat Build A Brighter Lamp :: Linux Apache {middleware} PostgreSQL
Robert Treat <xzilla@users.sourceforge.net> writes:
> On Thursday 23 March 2006 15:12, David Fetter wrote:
>> I'd like to make a Modest Proposal™: Let's take down the interactive
>> documents and, in their place, put up a request that doc patches be
>> sent to -docs.
> I'd say you're anti-interactive comments :-)
I concur. People *like* interactive comments, it seems, and we'd not
accomplish much by taking them away except to piss off the users.
What we do need is a better process for improving the docs in response
to what gets posted as interactive comments. I've tried in the past to
scan the interactive comments and incorporate what seemed worthwhile,
but it's a mighty tedious task.
> The other option would be to mail approved doc comments to this group so that
> someone could work them up into doc patches if applicable.
We could try this for awhile and see if it works.
regards, tom lane
On Thu, Mar 23, 2006 at 04:46:02PM -0500, Robert Treat wrote: > > ...and it's unlikely that they will, now or later, without > > somebody whose whole job is to monitor those comments and make > > patches. > > Well, we do make some attempt at rolling comments into the docs > where appropriate, but we could certainly use more dedicated > contributors in that area. If we're going to get dedicated contributors, we could direct their efforts to things a *lot* more productive than this. Improving the formal docs, for example. > > I'd like to make a Modest Proposalâ¢: Let's take down the > > interactive documents and, in their place, put up a request that > > doc patches be sent to -docs. > > > > What say? > > I'd say you're anti-interactive comments :-) I'm not against them. I'm just *for* improving the existing docs, and those comments don't (and won't, very likely) have any pipeline into those. Are you personally volunteering for this task, Robert? > More importantly, people just aren't going to to write patches for > doc additions... the overhead is several orders of magnitudes > greater than filling at a web form... so getting rid of the comments > is sure to lose any gains that we receive. What gains? As I said, I'm not against it, but right now, those things just go down the memory hole to the benefit of nobody. The detriment, I'd say, because somebody has wasted their time. > What I have tried to garner support for in the past was to either > direct those submission to this group for approval/rejection, which > would make the folks generally interested in docs directly involved > in the process. Somebody has to vet this. Please feel free to step up :) > The other option would be to mail approved doc comments to this > group so that someone could work them up into doc patches if > applicable. That really is a factor, most of the comments would need > to be reworded to be added into the docs proper. > > In the past these ideas were rejected as either off-topic or that it > would turn this list into a high traffic list... if peoples opinions > have changed, it could be arranged. I'm voicing a rejection for 'em again on the same grounds. Until we have a person whose paid, full-time job is web-comment rassling, this is a non-starter. Cheers, D -- David Fetter <david@fetter.org> http://fetter.org/ phone: +1 415 235 3778 AIM: dfetter666 Skype: davidfetter Remember to vote!
On Thursday 23 March 2006 17:46, David Fetter wrote:
> On Thu, Mar 23, 2006 at 04:46:02PM -0500, Robert Treat wrote:
> > > ...and it's unlikely that they will, now or later, without
> > > somebody whose whole job is to monitor those comments and make
> > > patches.
> >
> > Well, we do make some attempt at rolling comments into the docs
> > where appropriate, but we could certainly use more dedicated
> > contributors in that area.
>
> If we're going to get dedicated contributors, we could direct their
> efforts to things a *lot* more productive than this. Improving the
> formal docs, for example.
>
Uh, that's what we're talking about David, having someone who would be willing
to take doc comments and roll them into the formal docs.
> > > I'd like to make a Modest Proposalâ¢: Let's take down the
> > > interactive documents and, in their place, put up a request that
> > > doc patches be sent to -docs.
> > >
> > > What say?
> >
> > I'd say you're anti-interactive comments :-)
>
> I'm not against them. I'm just *for* improving the existing docs, and
> those comments don't (and won't, very likely) have any pipeline into
> those. Are you personally volunteering for this task, Robert?
>
Well David, I have actually already submitted multiple patches to the docs
directly based on documentation comments, check the archives. Also I know Tom
has gone through a number of times in the past in an attempt to cull
improvements. The things is, we're busy guys, so we can't exactly do it
alone. If we could get some more volunteers, the process would be better.
Even if we can't I still think it is worthwhile, but I'll cover that more in
a bit.
> > More importantly, people just aren't going to to write patches for
> > doc additions... the overhead is several orders of magnitudes
> > greater than filling at a web form... so getting rid of the comments
> > is sure to lose any gains that we receive.
>
> What gains? As I said, I'm not against it, but right now, those
> things just go down the memory hole to the benefit of nobody. The
> detriment, I'd say, because somebody has wasted their time.
>
Not true. First, there have been doc improvements based on those comments.
Furthermore, people do find the doc comments helpful; they find information
clearing things up online and when google searching. In fact more people
could be helped if things like the docbot pointed to the interactive docs,
though for some reason the guys running that thing refuse to do so.
> > What I have tried to garner support for in the past was to either
> > direct those submission to this group for approval/rejection, which
> > would make the folks generally interested in docs directly involved
> > in the process.
>
> Somebody has to vet this. Please feel free to step up :)
Um, maybe I wasn't clear when I said "I have tried to garner support", but I
have tried to garner support, and it got shot down. Can it be your turn now?
>
> > The other option would be to mail approved doc comments to this
> > group so that someone could work them up into doc patches if
> > applicable. That really is a factor, most of the comments would need
> > to be reworded to be added into the docs proper.
> >
> > In the past these ideas were rejected as either off-topic or that it
> > would turn this list into a high traffic list... if peoples opinions
> > have changed, it could be arranged.
>
> I'm voicing a rejection for 'em again on the same grounds. Until we
> have a person whose paid, full-time job is web-comment rassling, this
> is a non-starter.
>
Well there you go. You complain that the interactive docs aren't merged
upstream enough, but protest any effort to get subscribers from the _docs
mailing list_ involved.
--
Robert Treat
Build A Brighter Lamp :: Linux Apache {middleware} PostgreSQL
On Fri, Mar 24, 2006 at 08:58:55AM +0000, Dave Page wrote: > On 23/3/06 20:12, "David Fetter" <david@fetter.org> wrote: > > > On Thu, Mar 23, 2006 at 07:00:13PM +0100, Jim Nasby wrote: > >> On Mar 23, 2006, at 4:08 PM, Oisin Glynn wrote: > >> > >>> I just discovered that the comments from 8.0 had the answer I was > >>> looking for but these comments are not in the 8.1 docs. Should the > >>> comments be rolled forward as new versions are created? Or if valid > >>> comments added to the docs themselves? > >>> > >>> http://www.postgresql.org/docs/8.1/interactive/sql-copy.html > >>> > >>> http://www.postgresql.org/docs/8.0/interactive/sql-copy.html > >> > >> No, comments don't roll forward. > > > > ...and it's unlikely that they will, now or later, without somebody > > whose whole job is to monitor those comments and make patches. > > > > I'd like to make a Modest Proposal???: Let's take down the interactive > > documents and, in their place, put up a request that doc patches be > > sent to -docs. > > > > What say? > > I say no, because whilst some comments should (and do) end up in the docs, > many are simply useful real-world code examples and related information that > people post. It's useful stuff, but would clutter the docs. But now that stuff gets 'lost' with ever new major version. It'd probably be better if it was posted somewhere like http://www.pervasivepostgres.com/instantkb13/ -- Jim C. Nasby, Sr. Engineering Consultant jnasby@pervasive.com Pervasive Software http://pervasive.com work: 512-231-6117 vcard: http://jim.nasby.net/pervasive.vcf cell: 512-569-9461