On Mon, Nov 9, 2020 at 1:41 PM Tom Lane <tgl@xxxxxxxxxxxxx> wrote:
Alvaro Herrera <alvherre@xxxxxxxxxxxxxx> writes:
> On 2020-Nov-08, Adrian Klaver wrote:
>> Yeah, I would agree with the mobile first design comments. Then again that
>> plague is hitting most sites these days. My 2 cents is it is a step
>> backwards. You can cover more ground quickly and digest it faster in the old
>> format.
> The person who made that comment retracted later.
> If you have suggestion on how to improve the new format, I'm sure we can
> discuss that. It seems pretty clear to me that we're not going back to
> the old format.
I think there's no question that the new format is better in any case
where a function needs more than a couple words of documentation.
I could see the argument for adopting a more compact format for tables
that contain no such functions. I think you might find that the set of
such tables is nigh empty, though; even section 9.3 (mathematical
functions) has a lot of functions that need a sentence or two. We used
to either omit important details for such functions or stick them in
footnotes, and neither of those options is very nice.
My observation is that the new format reduces one's ability to quickly skim the table to find out what is present since there is considerable extra information in one's eyes during that process that needs to be skimmed over.
My suggestion is to add a "table of contents" at the top of non-trivial sections that simply lists available functions by name (generally ignoring argument variations) and a quick one line description of purpose. Once a person finds the name of the function that suits their needs they can then reference the main table for details, warnings, and examples.
This is what TOCs are for, no?
--
Angular momentum makes the world go 'round.
Angular momentum makes the world go 'round.
