Re: need for "see also" section or similar thing at hub pages

On Wed, Aug 5, 2020 at 5:29 PM Bruce Momjian <bruce(at)momjian(dot)us> wrote:

> On Tue, Aug 4, 2020 at 03:56:32PM +0000, PG Doc comments form wrote:
> > The following documentation comment has been logged on the website:
> >
> > Page: https://www.postgresql.org/docs/12/functions-textsearch.html
> > Description:
> >
> > A suggestion. This page, "functions-textsearch", is fine, and the best
> > place to explain functions like array_to_tsvector() and
> jsonb_to_tsvector().
> > The suggestion is just to cite these native functions in the Guide's "hub
> > page" of respective prefixes...
>
> > Simple citation anywhere in the hub page, or a simple "See also"
> section to
> > list the non-explained functions that can be also classifyed as valid
> > function for that hub page.
>
> Uh, I am not sure it helps to mention that there are text
> search-specific functions in the generic sections.
>

By that logic array_to_text should exist under string functions and not
array functions (I would seriously consider this specific change).
However, the premise that the array and json pages are "hub pages" is not
one that I support. They are not lacking information but simply do not
attempt to fulfill such a broad mandate. If a user wishs to know every
function/operator in their database that accepts an array as input or
outputs an array that would be better served by querying the database and
not scanning documentation. Nor do I find it plausible that given a
function name array_to_tsvector that is difficult to locate - even without
using search - if the function is only listed in the text search section.

In short, I see no usability gap here that needs to be fixed. I'll agree
that it could be different but I don't believe that it would be an obvious
improvement even if an actual patch were presented for discussion.

David J.