Date: Fri, 17 May 2019 10:16:26 -0400
From: Bruce Momjian <bruce@momjian.us>
To: Alvaro Herrera <alvherre@2ndquadrant.com>
Cc: Peter Geoghegan <pg@bowt.ie>, Michael Paquier <michael@paquier.xyz>,
	Amit Langote <Langote_Amit_f8@lab.ntt.co.jp>,
	David Rowley <david.rowley@2ndquadrant.com>,
	"Jonathan S. Katz" <jkatz@postgresql.org>,
	PostgreSQL Advocacy <pgsql-advocacy@lists.postgresql.org>
Subject: Re: PostgreSQL 12: Feature Highlights
Message-ID: <20190517141626.5xrlllzypehrm7cy@momjian.us>
References: <20190517013255.bera5dtuii376lae@momjian.us>
 <20190517023413.GA15079@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20190517023413.GA15079@alvherre.pgsql>
User-Agent: NeoMutt/20170113 (1.7.2)
Precedence: bulk

On Thu, May 16, 2019 at 10:34:13PM -0400, Alvaro Herrera wrote:
> On 2019-May-16, Bruce Momjian wrote:
> 
> > The release notes are written for the _average_ reader.
> 
> I disagree with this assertion, and frankly I cannot understand why you
> think that's the most useful thing to do.  The release notes are not a
> press release, where you have to make things pretty or understandable to
> everyone.  Users can skip items they don't understand or don't care
> about; but would at least be given the option.  If we don't document,
> we're making the decision for them that they must not care.

The press release is not an exhaustive list of all features, so we can't
just fall back on the press release as a way for non-internals readers
to understand all the features in this release.

Frankly, when I am reading a document, if I hit a few items I don't
understand, I stop reading.  This is why I tend to write in a
generally-accessible level of detail.  You can see this in all my
writings, e.g., blogs.  I don't know how to write differently without
feeling I am being inconsiderate to the reader.

Also, when I say I write for the average reader, I write for the average
person who is likely to read the document, not for the average person in
general.

I suggest you look at how Tom Lane writes the minor release notes for an
example that is better or worse than my style.

-- 
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +