On Wed, Nov 30, 2011 at 3:02 AM, Greg Smith <greg@2ndquadrant.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