Re: [HACKERS] 7.5 release notes - Mailing list pgsql-docs

Simon Riggs wrote:
> On Sun, 2004-07-25 at 05:25, Bruce Momjian wrote:
> > I have completed the 7.5 release notes.  You can view them in HTML on
> > the developer web page.  I have marked a few items with question marks
> > that need to be addressed.  I am looking for improvements, even minor
> > ones.  Either send in a patch or committers can modify the file
> > directly.
> >
>
> Looks good. These take time and effort, much appreciated.
>
> Forward-looking phrases
> =======================
>
> Overall, I'd ask that we don't refer back to what earlier releases
> didn't do, or whatever limitations they were thought to have.
>
> If a release has "new feature X", everybody can work out it wasn't there
> in the last release. The phrasing is delicate so you describe the new
> thing without running down the old.
>
> e.g. (1)
>
> Previous releases required the Unix emulation toolkit Cygwin for Win32
> support.
>
> to
>
> The server no longer relies upon Cygwin for Unix emulation under win32.
>
> e.g. (2)
>
> Prior release had no such capability; there was no way to recover from a
> statement failure in a transaction.
>
> to
>
> Should a statement fail inside a transaction, there is now a way to
> handle this error and continue processing.
>
> (Of course, somebody will let me know about my Brit-style passive voice,
> I'm sure...)

I understand your reason for making these changes.  However, I am unsure
if your new wording is as clear as the previous one.  Our reliance on
Cygwin and inability to prevent an error from aborting a transaction
were limitation and it seems clearer to just state that we have fixed
them rather than try to sugar-code our previous limitations.

Marketing-wise, I think you are right, but from an honesty/clarity
perspective, I think the current wording is better.  What I could do is
remove some of the later references where we were talking updating the
system catalog to do various things.  I am not sure it is needed.

Comments?


>
> Migration
> =========
> These release notes refer to "GUC"s, whereas the previous release notes
> and the manual refers to "server configuration parameters". I understand
> the former, but prefer the latter description for these user-focused
> notes.

Updated.

> Also, it might be worth mentioning that pg_dump itself has also been
> substantially improved, and now provides an improved upgrade path for
> existing users.

It is mentioned as the top item in the pg_dump section.  It doesn't seem
like a migration issue to me though.  Is it a major feature?

> Here's my attempt at a short paragraph for PITR...
>
> Point-In-Time Recovery enhances Data Resilience
>
> PostgreSQL can now recover from total disk failure using backups and
> transaction log archives. Recovery can be controlled to stop at a
> specified point in time or at some transaction in the past. Transaction
> log archiving is automated and calls a user-supplied external program to
> allow integration with external backup devices and related software.

We can improve the wording, but if the motivation is to reduced saying
bad things about our previous functionality, let me explain my
perspective.

Basically, my goal with these release notes is to make it as clear as
possible why this new feature would be valuable to the reader.  If it
makes our previous release look bad, so be it.  For me, clarity and
candor gain a lot more credibility than trying to cover over missing
functionality in the past.  I am not saying we have to be so honest that
we bash PostgreSQL, but in cases where we adjust wording to try to
prevent ourselves from looking bad, it is best to be honest and clear
about our limitations.  I think in the long run it gains us lots of
credibility (and ultimately volunteers).

>
> > Do people want a big-picture paragraph at the top talking about the
> > release?  Some releases get them, some don't, but this one could if
> > folks want it.
> >
>
> Yes, thats a good idea.

OK.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073