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

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

Ideal, for Guide reader, is to be informed about the existence of all array
functions in the Array's hub page,
https://www.postgresql.org/docs/current/functions-array.html , and all JSON
functions in the JSON's hub page
https://www.postgresql.org/docs/current/functions-json.html

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.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com

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

On Wed, Aug 5, 2020 at 5:29 PM Bruce Momjian <bruce@momjian.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.