public inbox for [email protected]  

help / color / mirror / Atom feed

From: Bruce Momjian <[email protected]>
To: Alvaro Herrera <[email protected]>
Cc: Peter Geoghegan <[email protected]>
Cc: Michael Paquier <[email protected]>
Cc: Amit Langote <[email protected]>
Cc: David Rowley <[email protected]>
Cc: Jonathan S. Katz <[email protected]>
Cc: PostgreSQL Advocacy <[email protected]>
Subject: Re: PostgreSQL 12: Feature Highlights
Date: Fri, 17 May 2019 10:16:26 -0400
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>
	<[email protected]>

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  <[email protected]>        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 +

view thread (63+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected]
  Subject: Re: PostgreSQL 12: Feature Highlights
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox