improve predefined roles documentation

From: Nathan Bossart <nathandbossart(at)gmail(dot)com>
To: pgsql-hackers(at)postgresql(dot)org
Subject: improve predefined roles documentation
Date: 2024-06-13 19:48:11
Message-ID: ZmtM-4-eRtq8DRf6@nathan
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

IMHO there are a couple of opportunities for improving the predefined roles
documentation [0]:

* Several of the roles in the table do not have corresponding descriptions
in the paragraphs below the table (e.g., pg_read_all_data,
pg_write_all_data, pg_checkpoint, pg_maintain,
pg_use_reserved_connections, and pg_create_subscription). Furthermore,
IMHO it is weird to have some of the information in the table and some
more in a paragraph down the page.

* The table has grown quite a bit over the years, but the entries are
basically unordered, requiring readers to perform a linear search (O(n))
to find information about a specific role.

* Documentation that refers to these roles cannot link to a specific one.
Currently, we just link to the page or the table.

I think we could improve matters by abandoning the table and instead
documenting these roles more like we document GUCs, i.e., each one has a
section below it where we can document it in as much detail as we want.
Some of these roles should probably be documented together (e.g.,
pg_read_all_data and pg_write_all_data), so the ordering is unlikely to be
perfect, but I'm hoping it would still be a net improvement.

Thoughts?

[0] https://www.postgresql.org/docs/devel/predefined-roles.html

--
nathan

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Andrew Dunstan 2024-06-13 19:53:17 Re: Shouldn't jsonpath .string() Unwrap?
Previous Message Andrew Dunstan 2024-06-13 19:33:50 Re: jsonpath: Missing Binary Execution Path?