On Tue, Jul 5, 2022 at 5:47 AM Alvaro Herrera <alvhe...@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
