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