Re: doc: BRIN indexes and autosummarize

On Tue, Jul 5, 2022 at 5:47 AM Alvaro Herrera <alvherre@alvh.no-ip.org>
wrote:

> OK, I have adopted all your proposed changes, thanks for submitting in
> both forms.  I did some more wordsmithing and pushed, to branches 12 and
> up.  11 fails 'make check', I think for lack of Docbook id tags, and I
> didn't want to waste more time.  Kindly re-read the result and let me
> know if I left something unaddressed, or made something worse.  The
> updated text is already visible in the website:
> https://www.postgresql.org/docs/devel/brin-intro.html
>

You removed the reference to the functions' documentation at
functions-admin-index choosing instead to duplicate a summarized
version of the docs, and to boot getting the next block to be blobbed
together with it.

Keeping with the reduced-readability theme, you made the paragraphs
even bigger. While I do appreciate the time to clarify things a bit, as was
my original intent with the patch,

We should be writing documentation with the user in mind, not for our
developer eyes. Different target audiences. It is less helpful to have
awesome features that don't get used because users can't really
grasp the docs.

Paragraphs such as this feel like we're playing "summary bingo":

     When a new page is created that does not fall within the last
     summarized range, the range that the new page belongs into
     does not automatically acquire a summary tuple;
     those tuples remain unsummarized until a summarization run is
     invoked later, creating the initial summary for that range

Roberto

--
Crunchy Data -- passion for open source PostgreSQL