From: Jonathan S. Katz <jkatz@postgresql.org>
To: Tom Lane <tgl@sss.pgh.pa.us>
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Cc: Daniel Gustafsson <daniel@yesql.se>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Formatting of warning about using ident
Date: Mon, 22 Jul 2019 11:30:01 -0400
Message-ID: <bc4308bc-2e4c-3f2f-990f-30102380f68f@postgresql.org> (raw)
In-Reply-To: <23574.1563804571@sss.pgh.pa.us>
References: <B20006D2-AE84-40CE-97DE-A607A0027EE0@yesql.se>
<bc0f78d9-c7e5-1804-9cc1-2fe30f16d2a2@2ndquadrant.com>
<D7DCADB0-D7E7-4C1B-ACFD-7C1AD466EFE5@yesql.se>
<05d9e235-118f-2dbc-95c3-e1a51c19dad1@2ndquadrant.com>
<23574.1563804571@sss.pgh.pa.us>
On 7/22/19 10:09 AM, Tom Lane wrote:
> Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
>> In general, I would argue in favor of fewer "note", "warning", etc.
>> Some documentation pages are now just a sequence of "note"s and little
>> proper text. If the normal text properly explains a topic and its pros
>> and cons, then we don't need all that extra decoration and it makes the
>> text easier to read.
>
> +1. With the way these things are rendered in the current HTML output,
> they are so visually distracting that they ought to be reserved for
> absolutely critical info. I almost feel that we should ban <note>
> entirely, because the rendering is completely disproportional to the
> meaning.
Based on the example of auth-ident.html, removing "note" seems to make
sense. It just seems like it's a part of the regular documentation.
However, perhaps the reason people feel the need to highlight such
things is that they want to ensure the reader catches an important
point, particularly as one is often reading the documentation quickly to
find the piece of info they're looking for (speaking from personal
experience).
That said, looking through some other pages, the "notes" feel like
they're other "asides" to add more detail around a particular point, or
calling out a specific fact. It seems like they could be inlined as part
of the regular documentation.
Something like a "warning" should be visually distracting...it's a
warning that the user could end up in a dangerous situation with their
data, so they should heed it.
> (Or, maybe, somebody could tinker with the stylesheets?)
I think lessening the use of "note" would help. It would require some
rewriting in places it's being used. That way, if we need something
that's truly a "warning" we won't feel as hesitant to add it to the docs.
Thanks,
Jonathan
Attachments:
signature.asc (application/pgp-signature, 832B) download
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: pgsql-docs@postgresql.org
Cc: jkatz@postgresql.org, tgl@sss.pgh.pa.us, peter.eisentraut@2ndquadrant.com, daniel@yesql.se, pgsql-docs@lists.postgresql.org
Subject: Re: Formatting of warning about using ident
In-Reply-To: <bc4308bc-2e4c-3f2f-990f-30102380f68f@postgresql.org>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox