Skip site navigation (1) Skip section navigation (2)

Re: Word-smithing doc changes

From: Robert Haas <robertmhaas(at)gmail(dot)com>
To: Greg Smith <greg(at)2ndquadrant(dot)com>
Cc: Bruce Momjian <bruce(at)momjian(dot)us>, Alvaro Herrera <alvherre(at)commandprompt(dot)com>, Greg Stark <stark(at)mit(dot)edu>, "<pgsql-hackers(at)postgresql(dot)org>" <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: Word-smithing doc changes
Date: 2011-11-30 13:18:44
Message-ID: CA+TgmoaYFC0sJ8X1+tr4zLKuY6Wm7=Bj_XN=1QdoCzpGLiuV3g@mail.gmail.com (view raw or flat)
Thread:
Lists: pgsql-hackers
On Wed, Nov 30, 2011 at 3:02 AM, Greg Smith <greg(at)2ndquadrant(dot)com> wrote:
> I will happily accept that the description there may have suffered from me
> not using all of the terms optimally, and that the resulting commit could be
> improved.  Some more feedback to get the description correct and useful
> would be much appreciated.
>
> What I cannot agree with is that idea that the implementation details I
> suggested documenting should not be.  There are extremely user-hostile
> things that can happen here, and that are unique to this command.  Saying
> "this is too complicated for users to make heads or tails of" may very well
> be true in many cases, but I think it's not giving PostgreSQL users very
> much credit.  And when problems with this happen, and I wouldn't have spent
> any time on this if they didn't, right now the only way to make heads or
> tails of it is to read the source code.

+1.

If we only document approximately how it works, then that's less work,
but it's also less useful.  Greg's attempt to document *exactly* how
it works was kind of klunky, but I think that can and should be
improved, not replaced with wording that's more vague and therefore
easier to write.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

In response to

pgsql-hackers by date

Next:From: Andrew DunstanDate: 2011-11-30 13:58:04
Subject: Re: Java LISTEN/NOTIFY client library work-around
Previous:From: Robert HaasDate: 2011-11-30 13:10:00
Subject: Re: synchronous commit vs. hint bits

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group