WIP

docs/docs/user-guide/access-control.md

@@ -4,11 +4,13 @@ To manage access to data, Mathesar utilizes PostgreSQL's powerful role-based per
 
 Here's how it works:
 
-1. Within PostgreSQL, privileges on data can be granted to different **[PostgreSQL roles](./roles.md)** at a granular level. Mathesar respects these privileges and also exposes functionality for you to see and modify them via [Database Permissions](./databases.md#permissions), [Table Permissions](./tables.md#permissions), and [Column Permissions](./columns.md#permissions).
+1. **Roles:** Within PostgreSQL, privileges on data can be granted to different **[PostgreSQL roles](./roles.md)** at a granular level. Mathesar respects these privileges and also exposes functionality for you to see and modify them via [Database Permissions](./databases.md#permissions), [Table Permissions](./tables.md#permissions), and [Column Permissions](./columns.md#permissions).
 
-1. Each **[Mathesar user](./users.md)** accesses a database through a specific PostgreSQL role. The user's access is determined by the role's privileges within PostgreSQL.
+1. **Users:** Each **[Mathesar user](./users.md)** accesses a database through a specific PostgreSQL role. The user's access is determined by the role's privileges within PostgreSQL.
 
-1. The mapping between Mathesar users and PostgreSQL roles is done one a per-database level via the concept of **[collaborators](./collaborators.md)**. So one Mathesar user can be configured to use different PostgreSQL roles for different databases on the same server.
+    (Note that the user's [admin status](./users.md#admin) within Mathesar _has no effect_ on the user's ability to do things with the _data_ in a database! The admin status only affects higher-level operations like adding/removing databases, users, and collaborators.)
+
+1. **Collaborators:** The mapping between Mathesar users and PostgreSQL roles is done on a per-database level via the concept of **[collaborators](./collaborators.md)**. So, one Mathesar user can be configured to use different PostgreSQL roles for different databases on the same server.
 
 Mathesar [metadata](./metadata.md) and [data explorations](./data-explorer.md) are currently readable and writable by all collaborators on a database, regardless of their PostgreSQL role's permissions or their [user's admin status](./users.md#admin). If you need to restrict access to metadata or data explorations, we would be curious to hear about your use case and welcome you to [open an issue](https://github.com/mathesar-foundation/mathesar/issues) to discuss it.
 

docs/docs/user-guide/collaborators.md

@@ -1,56 +1,38 @@
 # Collaborators
 
+For every database you connect in Mathesar, you can manage the access that your Mathesar users have to that database by adding them as collaborators. Each collaborator is associated with a PostgreSQL role that determines their permissions on the data.
 
-### _In Mathesar:_ Collaborators
+Only [Mathesar admin users](./users.md#admin) can manage collaborators.
 
-A "collaborator" is a Mathesar user who has access to a database through a specific PostgreSQL role.
+When you add a new database connection to Mathesar, your Mathesar user will automatically be added as a collaborator using the PostgreSQL role you specify at connection time.
 
-The Collaborators section allows you to add and remove collaborators and edit their corresponding PostgreSQL roles.
+## Adding a collaborator
 
-!!! tip "Keep in mind"
+!!! info "Prerequisites"
+    Before you can add a new collaborator:
 
-    - You'll only be able to choose roles that have been "configured" in the above section — roles for which Mathesar has passwords stored.
+    - Your [database](./databases.md) must be connected already.
+    - The [user](./users.md) must already exist in Mathesar.
+    - The [role](./roles.md) must already exist in PostgreSQL. (If needed, uou can use Mathesar to [add new role](./roles.md#managing) before creating a collaborator.)
 
-    - Removing a collaborator revokes that user's access to the database _but_:
+1. Navigate to the page for your connected database.
+1. Click on the **Database Settings** tab.
+1. Click on **Collaborators** in the left-hand menu.
+1. Click **Add Collaborator**.
 
-        - If the user is a Mathesar [admin](./users.md#admin), they'll be able to gain access again.
-        - The user will still remain in Mathesar, potentially with access to other Databases.
-        - The role (and its corresponding password) will still remain configured in Mathesar.
-        - The role will still remain on the PostgreSQL server.
+## Removing a collaborator
 
+Removing a collaborator revokes that user's access to the database _but_:
 
+- If the user is a Mathesar [admin](./users.md#admin), they'll be able to gain access again by adding their user back as a collaborator.
+- The user will still remain in Mathesar, potentially with access to other Databases.
+- The role (and its corresponding password) will still remain configured in Mathesar.
+- The role will still remain on the PostgreSQL server.
 
-
-### _In Mathesar:_ Role Configuration
-
-Use this section to manage the credentials (i.e. passwords) for roles that you'd like to assign to collaborators within Mathesar. Mathesar will display all [LOGIN roles](https://www.postgresql.org/docs/current/role-attributes.html#ROLE-ATTRIBUTES) that exist on the server.
-
-- Click **Configure in Mathesar** to store the role's password in Mathesar and allow the role to be associated with collaborators.
-
-- Click **Configure Password** to update the password of an already configured role.
-
-- Click **Remove** to remove Mathesar's stored password for a role. The role will remain on the server.
-
-
-## Users vs Roles vs Collaborators
-
-- A **[user](./users.md)** is a Mathesar construct. Each Mathesar installation has multiple users.
-- A **role** is a PostgreSQL construct. (See [PostgreSQL docs](https://www.postgresql.org/docs/current/user-manag.html)). Each PostgreSQL server has multiple roles and multiple databases.
-
-!!! caution "Why this distinction is important"
-    Outside of Mathesar, it's not uncommon for people to say _user_ when referring to a PostgreSQL _role_. However, within the context of Mathesar users and roles are different things! Our documentation maintains this distinction pedantically.
-
-How users and roles work together:
-
-- To access a database, each Mathesar user must be assigned a PostgreSQL role to be used for that database.
-- The user's permissions on actual data (i.e. _not_ Mathesar [metadata](./metadata.md)) are determined by the corresponding role's permissions within PostgreSQL.
-
-    !!! info "Admin doesn't matter here"
-        The user's "admin" status with Mathesar _has no effect_ on the user's ability to do things with the _data_ in a database! The admin status only affects higher-level operations like adding/removing databases, users, and collaborators.
+## Configuration patterns
 
 - You can configure separate Mathesar users to share the same PostgreSQL role if you like. This is a good option if you want those users to have the same permissions on the data.
 - Or you can use separate PostgreSQL roles for different users. This is necessary any time you want different users to have different permissions on the data.
-- You cannot configure one Mathesar user with two PostgreSQL role simultaneously — though you can save multiple PostgreSQL roles in Mathesar and manually switch between them if necessary.
+- You cannot configure one Mathesar user with two PostgreSQL role simultaneously — though you can save multiple PostgreSQL roles in Mathesar and manually switch between them if necessary. You won't even need to enter the role's password each time you switch, since it will be saved in Mathesar.
 
-See [Permissions](./permissions.md) for more information on managing roles.
 

docs/docs/user-guide/roles.md

@@ -2,8 +2,6 @@
 
 PostgreSQL uses roles to manage access to data, and each PostgreSQL server has many roles within it.
 
-To see the roles available on your server, navigate to the **Database Settings** section within the page for one of your connected databases.
-
 ## What is a role
 
 PostgreSQL role system is elegant and powerful, if albeit somewhat idiosyncratic.
@@ -15,6 +13,14 @@ Other permissioning systems also commonly have a _separate_ concept of "groups",
 !!! warning "Users vs Roles"
     Outside of Mathesar, it’s not uncommon for people to say _user_ when referring to a PostgreSQL _role_. However, within the context of Mathesar, users and roles are different things! Our documentation maintains this distinction pedantically. When we say "user", we mean a _Mathesar_ user, and when we say "role", we mean a _PostgreSQL_ role.
 
+## Managing your PostgreSQL roles from within Mathesar {:#managing}
+
+To see the roles available on your server, navigate to the **Database Settings** tab within the page for one of your connected databases. From there, you'll be able to add roles, drop roles, and edit role inheritance.
+
+Role passwords are stored in Mathesar's internal database and encrypted with your [SECRET_KEY](../configuration/env-variables.md#secret_key).
+
+Renaming roles and modifying role properties (e.g. `LOGIN` status) is not supported within Mathesar.
+
 ## LOGIN vs non-LOGIN roles
 
 In PostgreSQL every role has a boolean `LOGIN` property which is either _true_ or _false_. A `LOGIN` role may have an associated password and thus be used to connect to the server; while a non-`LOGIN` role may not. Non-`LOGIN` roles are often used as "group" roles to be granted to other roles.