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 |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
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
From | Date | Subject | |
---|---|---|---|
Next Message | Andrew Dunstan | 2011-11-30 13:58:04 | Re: Java LISTEN/NOTIFY client library work-around |
Previous Message | Robert Haas | 2011-11-30 13:10:00 | Re: synchronous commit vs. hint bits |