Re: [GENERAL] COPY command documentation

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