RE: Version 13 documentation layout is harder to read than version 12 - Mailing list pgsql-docs

I have two observations:

1. I do have a wide monitor, so I have not been as aware of the version 12 documentation issues. I see that the way scaling was implemented in version 12 on a small screen could be problematic, but it is still easier to read on a laptop screen than version 13. See screen shots:
   1. 
   2. 
2. Is there a middle ground?
   1. Version 12 had 6 columns, version 13 has one.
   2. 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.
   3. We could fix (or remove) the zoom that makes the text unreadable when the page is resized.
   4. The new approach uses just a small part of the screen width, when we really need to use more.

Niels

-----Original Message-----
From: Bruce Momjian <bruce@momjian.us>
Sent: Tuesday, September 29, 2020 08:16
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Niels Andersen <niels@thinkiq.com>; pgsql-docs@lists.postgresql.org
Subject: Re: Version 13 documentation layout is harder to read than version 12

On Tue, Sep 29, 2020 at 09:52:31AM -0400, Tom Lane wrote:

> PG Doc comments form <noreply@postgresql.org> writes:

> > Compare:

> > * https://www.postgresql.org/docs/13/functions-json.html

> > * https://www.postgresql.org/docs/12/functions-json.html

>

> > I know it is just my opinion, but the version 12 layout is easier to

> > read than version 13.

>

> IMO, table 9.47 (JSON Processing Functions) is pretty much the poster

> child for why we had to redesign the table layout.  In the old layout,

> it's close to unreadable in any normal-size browser window, despite

> wasting lots of whitespace and having large amounts of important info

> shuffled off into "Note" blocks.  The new layout is far more adaptable

> to viewing windows that aren't full-screen-width; and the "Note" text

> has all been merged into the table, so that you don't have to scroll

> down and back to find all the info about a function.

>

> I'll concede that it's a bit of a shock at first if you are used to

> the old layout.  But the developer community has been looking at this

> format for six months or so now, and I think people grew accustomed to

> it fairly quickly.

I think the issue is that the PG 12 format is easier to scan a single column, while the PG 13 format is easier to read.

--

  Bruce Momjian  <bruce@momjian.us>        https://momjian.us

  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee