From: Robert Treat <xzilla@users.sourceforge.net>
To: pgsql-general@postgresql.org
Subject: Re: [GENERAL] COPY command documentation
Date: Thu, 23 Mar 2006 19:51:14 -0500
User-Agent: KMail/1.8.3
Cc: David Fetter <david@fetter.org>, pgsql-docs@postgresql.org,
	Jim Nasby <jnasby@pervasive.com>, Oisin Glynn <me@oisinglynn.com>
References: <4422B9F8.60100@oisinglynn.com>
	<200603231646.02465.xzilla@users.sourceforge.net>
	<20060323224651.GD6106@fetter.org>
In-Reply-To: <20060323224651.GD6106@fetter.org>
MIME-Version: 1.0
Content-Type: text/plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline
Message-Id: <200603231951.15141.xzilla@users.sourceforge.net>

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 will=
ing=20
to take doc comments and roll them into the formal docs.=20

> > > I'd like to make a Modest Proposal=E2=84=A2:  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=
=20
directly based on documentation comments, check the archives. Also I know T=
om=20
has gone through a number of times in the past in an attempt to cull=20
improvements.  The things is, we're busy guys, so we can't exactly do it=20
alone.  If we could get some more volunteers, the process would be better.=
=20
Even if we can't I still think it is worthwhile, but I'll cover that more i=
n=20
a bit.  =20

> > 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.=
=20
=46urthermore, people do find the doc comments helpful; they find informati=
on=20
clearing things up online and when google searching. In fact more people=20
could be helped if things like the docbot pointed to the interactive docs,=
=20
though for some reason the guys running that thing refuse to do so. =20

> > 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=20
have tried to garner support, and it got shot down.  Can it be your turn no=
w?=20

>
> > 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=20
upstream enough, but protest any effort to get subscribers from the _docs=20
mailing list_ involved.  =20

=2D-=20
Robert Treat
Build A Brighter Lamp :: Linux Apache {middleware} PostgreSQL