Feedback-ID: ia2694551:Fastmail
Date: Tue, 5 Jul 2022 21:46:57 +0200
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
To: Roberto Mello <roberto.mello@gmail.com>
Cc: Jaime Casanova <jcasanov@systemguards.com.ec>,
	Justin Pryzby <pryzby@telsasoft.com>,
	PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>
Subject: Re: doc: BRIN indexes and autosummarize
Message-ID: <20220705194657.nvrle2hbtxqop3yk@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: 
 <CAKz==bLHqX-0J_EajDe6rdEwT0GxbzxjgZVMEy8UFL03CD77rw@mail.gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/20220705194657.nvrle2hbtxqop3yk%40alvherre.pgsql>
Precedence: bulk

On 2022-Jul-05, Roberto Mello wrote:

> 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.

Actually, my first instinct was to move the interesting parts to the
functions docs, then reference those, removing the duplicate bits.  But
I was discouraged when I read it, because it is just a table in a place
not really appropriate for a larger discussion on it.  Also, a reference
to it is not direct, but rather it goes to a table that contains a lot
of other stuff.

> 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, [...]

Hmm, which paragraph are you referring to?  I'm not aware of having made
any paragraph bigger, quite the opposite.  In the original text, the
paragraph "At the time of creation," is 13 lines on a browser window
that is half the screen; in the patched text, that has been replaced by
three paragraphs that are 7, 6, and 4 lines long, plus a separate one
for the de-summarization bits at the end of the page, which is 3 lines
long.

> 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.

I try to do that.  I guess I fail more frequently that I should.

> 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

Yeah, I am aware that the word "summary" and variations occur way too
many times.  Maybe it is possible to replace "summary tuple" with "BRIN
tuple" for example; can you propose some synonym for "summarized" and
"unsummarized"?  Perhaps something like this:

>      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 BRIN tuple;
>      those [pages] remain uncovered by the BRIN index until a summarization run is
>      invoked later, creating the initial BRIN tuple for that range

(I also replaced the word "tuples" with "pages" in one spot.)

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/
"Hay dos momentos en la vida de un hombre en los que no debería
especular: cuando puede permitírselo y cuando no puede" (Mark Twain)