Content-Type: text/plain;
	charset=us-ascii
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3776.700.51.11.2\))
Subject: Re: Adding an explaining title to Notes on SGML
From: Daniel Gustafsson <daniel@yesql.se>
In-Reply-To: 
 <CAB-JLwY4izzCHDjS=Xb0KMc7uXbg6JjuMdRA2ri2CqYbeMDMEw@mail.gmail.com>
Date: Thu, 23 Apr 2026 09:55:28 +0200
Cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Content-Transfer-Encoding: quoted-printable
Message-Id: <778F991A-3BF8-4618-8F2E-3C503063F650@yesql.se>
References: 
 <CAB-JLwY4izzCHDjS=Xb0KMc7uXbg6JjuMdRA2ri2CqYbeMDMEw@mail.gmail.com>
To: Marcos Pegoraro <marcos@f10.com.br>
Archived-At: 
 <https://www.postgresql.org/message-id/778F991A-3BF8-4618-8F2E-3C503063F650%40yesql.se>
Precedence: bulk

> On 22 Apr 2026, at 20:59, Marcos Pegoraro <marcos@f10.com.br> wrote:
>=20
> I noticed that a "This" was missing when reading the Notes of the =
Aggregates page, so I thought... wouldn't it be better if we had a title =
in some of the Notes ?=20
> Because in many cases, like this example, you have a huge table and =
below it a Notes. But what is this Notes talking about ?=20

Notes are IMHO useful when they cause the reader to reflect on the =
<para> they
just read.

I think it's an antipattern to have notes so far removed from the =
relevant
<para> that we need a title for it.  A reader looking for info on =
count() will
find it in the table and read it - we can't really expect them to keep
scrolling a few pages down to see if there might be more info that =
wasn't
linked to.

Wouldn't it make more sense to refactor to move the information in the =
note
closer to what the note is regarding?

--
Daniel Gustafsson