Re: New "function tables" in V13 documentation

On Mon, Nov 9, 2020 at 1:41 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org> 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.

David J.