Re: Word-smithing doc changes

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