From: Tom Lane <tgl@sss.pgh.pa.us>
To: Niels Andersen <niels@thinkiq.com>
Cc: Bruce Momjian <bruce@momjian.us>
Cc: pgsql-docs@lists.postgresql.org <pgsql-docs@lists.postgresql.org>
Subject: Re: Version 13 documentation layout is harder to read than version 12
Date: Tue, 29 Sep 2020 15:00:13 -0400
Message-ID: <714873.1601406013@sss.pgh.pa.us> (raw)
In-Reply-To: <BY5PR11MB4183B74112E32B2DC39A64B0A0320@BY5PR11MB4183.namprd11.prod.outlook.com>
References: <160135280918.659.8300614023795573502@wrigleys.postgresql.org>
<608344.1601387551@sss.pgh.pa.us>
<20200929151620.GA26841@momjian.us>
<BY5PR11MB4183B74112E32B2DC39A64B0A0320@BY5PR11MB4183.namprd11.prod.outlook.com>
Niels Andersen <niels@thinkiq.com> writes:
> 2. Is there a middle ground?
> * Version 12 had 6 columns, version 13 has one.
> * Could we have fewer columns? What if we had 3 columns: One for operator or function, one for the details and description, and one for an example with the results.
A lot of these tables *did* have three columns before. They were still too
wide. See e.g. "Table 9.88 Replication SQL Functions" in the v12 docs.
Moreover, in a lot of places functions were just ridiculously
under-documented because of the tiny amount of space available.
If you compare v12 and v13 closely you'll notice that there's more
text for many functions (9.35 Geometric Operators is a handy example);
and there's room to add more now, wherever we need to.
Note that another reason for making these changes was so that the
tables would render in a less-than-completely-unreadable fashion in PDF
output, which is a good deal narrower than what most people use for
web browser windows (and a good deal less forgiving of overruns, too).
But I think it's a net benefit for HTML output as well, in that the
output does adapt much better than before to smaller window sizes.
Not everybody wants to dedicate their whole screen to Postgres docs.
Anyway, a very large amount of effort went into this redesign this
past spring, and we already tried a lot of variants, and already went
through the predictable complaints within the developer community.
I'm disinclined to redesign it again right now. If people are still
unhappy in a year or so, maybe there will be some appetite for a revisit.
regards, tom lane
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: tgl@sss.pgh.pa.us, niels@thinkiq.com, bruce@momjian.us, pgsql-docs@lists.postgresql.org
Subject: Re: Version 13 documentation layout is harder to read than version 12
In-Reply-To: <714873.1601406013@sss.pgh.pa.us>
* 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