To: Tom Lane <tgl@sss.pgh.pa.us>, Niels Andersen <niels@thinkiq.com>
Cc: Bruce Momjian <bruce@momjian.us>,
 "pgsql-docs@lists.postgresql.org" <pgsql-docs@lists.postgresql.org>
References: <160135280918.659.8300614023795573502@wrigleys.postgresql.org>
 <608344.1601387551@sss.pgh.pa.us> <20200929151620.GA26841@momjian.us>
 <BY5PR11MB4183B74112E32B2DC39A64B0A0320@BY5PR11MB4183.namprd11.prod.outlook.com>
 <714873.1601406013@sss.pgh.pa.us>
From: "Jonathan S. Katz" <jkatz@postgresql.org>
Autocrypt: addr=jkatz@postgresql.org; keydata=
 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 FmEC
Subject: Re: Version 13 documentation layout is harder to read than version 12
Message-ID: <9ee29735-cd44-4795-c6dd-cf9f6c846a3d@postgresql.org>
Date: Tue, 29 Sep 2020 15:09:58 -0400
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:68.0)
 Gecko/20100101 Thunderbird/68.12.0
MIME-Version: 1.0
In-Reply-To: <714873.1601406013@sss.pgh.pa.us>
Content-Type: multipart/signed; micalg=pgp-sha256;
 protocol="application/pgp-signature";
 boundary="HDUfMBroptsbCJvMiX0dgMXz8qKID5vjJ"
Precedence: bulk

This is an OpenPGP/MIME signed message (RFC 4880 and 3156)
--HDUfMBroptsbCJvMiX0dgMXz8qKID5vjJ
Content-Type: multipart/mixed; boundary="OAnpBkLiMo8St9xu8fvZZWwpb9HGbAUZ1";
 protected-headers="v1"
From: "Jonathan S. Katz" <jkatz@postgresql.org>
To: Tom Lane <tgl@sss.pgh.pa.us>, Niels Andersen <niels@thinkiq.com>
Cc: Bruce Momjian <bruce@momjian.us>,
 "pgsql-docs@lists.postgresql.org" <pgsql-docs@lists.postgresql.org>
Message-ID: <9ee29735-cd44-4795-c6dd-cf9f6c846a3d@postgresql.org>
Subject: Re: Version 13 documentation layout is harder to read than version 12
References: <160135280918.659.8300614023795573502@wrigleys.postgresql.org>
 <608344.1601387551@sss.pgh.pa.us> <20200929151620.GA26841@momjian.us>
 <BY5PR11MB4183B74112E32B2DC39A64B0A0320@BY5PR11MB4183.namprd11.prod.outlook.com>
 <714873.1601406013@sss.pgh.pa.us>
In-Reply-To: <714873.1601406013@sss.pgh.pa.us>

--OAnpBkLiMo8St9xu8fvZZWwpb9HGbAUZ1
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: quoted-printable

On 9/29/20 3:00 PM, Tom Lane wrote:
> 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 fo=
r operator or function, one for the details and description, and one for =
an example with the results.
>=20
> 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.=

>=20
> 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.
>=20
> 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.

I'll also note it helps on mobile viewing as well. We (likely the royal
"we" in this case) still need to figure out some things with the font
size on mobile to make it a bit easier to read, but the measurable
readability of the tables in the v13 docs is better than v12 on smaller
browsing windows.

> 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 revisi=
t.

I would say on this particular page, the only thing I find slightly
confusing is when the "->" operator is being described ("json -> integer
-> json"), but I think that may just be an unfortunate happenstance and
not grounds for redesign, at least at this time.

In recent times (which likely extends to the before times), I've found
when we've rolled out any UI/UX changes across pgweb properties there is
a mix of love/hate that is based on personal preference, which may or
may not coincide with what the overall goal of the change was.

If there is something that in a defined way is hampering usability, then
we should address it, but otherwise, per Tom's analysis, I would let
this bake a bit more and see if we want to make improvements towards the
end of the v14 development cycle.

Jonathan


--OAnpBkLiMo8St9xu8fvZZWwpb9HGbAUZ1--

--HDUfMBroptsbCJvMiX0dgMXz8qKID5vjJ
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: OpenPGP digital signature
Content-Disposition: attachment; filename="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCAAdFiEE+oS2la8r95ogZD/x8QSccp8cZScFAl9zhoYACgkQ8QSccp8c
ZSdzvBAAm1CK1ysfUHJxP1YHuUyEbPy9G84Z9nTFDaVRn+l/a06NaDrDGReiLybz
M2mBZOigDv9RBvJb+43jGBZaL0rIQZWi36Ro3Br0BWEq4QEPQqPaHR/z7CBrsQem
gQMaoMh2hsVlQEEvJtTlGiWAqbYAaT8xWq6psHoAcCD3MjQ/6TtGxcLcHumzmfhi
rGswB3+cB2I4dOiumpiFUuURtleXaMNdQ+Ke89mb+M1k3M/bVlEnUgFwAC6UMrQi
zlVvo2J9nt4G1jL08J6wl865dTYv2vAXLJUugrAPzMaxGwRVs2RMns4wD0WW+VGA
Glt0HbmGOg0KAn7LATy5z99q58dq2248JAYc7NP+7coVuiN3z0GgiadzFix/4/CD
4kuAEjb8n+hT78NBaBeeUTWHUyzfvwgndy/TSKE/3bywwHDEteKi9m6VkyfEpUr1
uoUhFPibblVyUoTCF9PU6sEYsOvWnAV3A0IAIgNJVkpEjUtW4i8U8ZNcSZU34UOk
ZcBzln5C0oqR4bdGXIKpuoFPXZ+xypSyDU4kD5BBa+qouIV+eJvCD+mC8m7GaDs0
fUhzXYniLu9xfHMMoaiUNGSKOSlC2egHbbjy7fDKIt98ejNa3T1Kg+Kksjya+iab
O8dMY2FLD6DSrOCiTyajyyfASSyy/Pf9Rhebn693HAWCk+Y9xG4=
=JsIJ
-----END PGP SIGNATURE-----

--HDUfMBroptsbCJvMiX0dgMXz8qKID5vjJ--