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