Horton

Re: Word-smithing doc changes

Robert Haas <robertmhaas@gmail.com>

View thread
From: Robert Haas <robertmhaas@gmail.com>
To: Greg Smith <greg@2ndquadrant.com>
Cc: Bruce Momjian <bruce@momjian.us>, Alvaro Herrera <alvherre@commandprompt.com>, Greg Stark <stark@mit.edu>, "<pgsql-hackers@postgresql.org>" <pgsql-hackers@postgresql.org>
Date: 2011-11-30T13:18:44Z
Lists: pgsql-hackers

Commits

Same data as JSON: GET /api/v1/messages/:b64id/commits the thread's linked commits as JSON, with link sources. API reference →

  1. Expand warnings on locks acquired by CREATE INDEX CONCURRENTLY

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