From: Tom Lane <tgl@sss.pgh.pa.us>
To: Niels Andersen <niels@thinkiq.com>
cc: Bruce Momjian <bruce@momjian.us>,
        "pgsql-docs@lists.postgresql.org" <pgsql-docs@lists.postgresql.org>
Subject: Re: Version 13 documentation layout is harder to read than version 12
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>
Comments: In-reply-to Niels Andersen <niels@thinkiq.com>
	message dated "Tue, 29 Sep 2020 18:21:08 -0000"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <714872.1601406013.1@sss.pgh.pa.us>
Content-Transfer-Encoding: quoted-printable
Date: Tue, 29 Sep 2020 15:00:13 -0400
Message-ID: <714873.1601406013@sss.pgh.pa.us>
Precedence: bulk

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 to=
o
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