chore(docs): refine the roles-and-permissions document (#675)

Co-authored-by: Nick Gagliardi <[email protected]>
Co-authored-by: Raghd Hamzeh <[email protected]>

Author: 3 people

docs/content/modeling/roles-and-permissions.mdx

@@ -21,19 +21,19 @@ import {
 
 <DocumentationNotice />
 
-In this guide you will learn how to model roles and permissions model within <ProductName format={ProductNameFormat.ProductLink}/> using the _<ProductConcept section="what-is-an-authorization-model" linkName="authorization model" />_ and _<ProductConcept section="what-is-a-relationship-tuple" linkName="relationship tuple" />_.
+To model roles and permissions in <ProductName format={ProductNameFormat.ProductLink}/> using <ProductConcept section="what-is-an-authorization-model" linkName="authorization models" /> and <ProductConcept section="what-is-a-relationship-tuple" linkName="relationship tuples" />. For the purpose of this guide:
 
-- **Roles** are assigned to <ProductConcept section="what-is-a-user" linkName="users" /> or a group of users, where any user can have more than one role (`editor`, `owner`, etc..).
-- **Permissions** are what allows users to access certain <ProductConcept section="what-is-an-object" linkName="objects" /> based on their specific roles (`device_renamer`, `channel_archiver`, etc..).
+- **Roles** are assigned to <ProductConcept section="what-is-a-user" linkName="users" /> or groups of users, where any user can have more than one role, like `editor` or `owner`.
+- **Permissions** allow users to access certain <ProductConcept section="what-is-an-object" linkName="objects" /> based on their specific roles, like `device_renamer` or `channel_archiver`.
 
-For example, the role `viewer` of a `trip` can have **permissions to view bookings** or the role `owners` can have **permissions to add/view bookings to a trip.**
+For example, the role `viewer` of a `trip` can have permissions to view bookings, while the role `owners` has permissions to add or view bookings to a trip.
 
 <CardBox title="When to use" appearance="filled">
 
-When trying to create a role and permissions model within <ProductName format={ProductNameFormat.ShortForm}/>.:
+When creating a role and permissions model within <ProductName format={ProductNameFormat.ShortForm}/>, you should:
 
-- Create roles by creating relations that can be directly assigned to users
-- Assign permissions by creating relations that users get through other relations
+- Create roles by creating relations that can be directly assigned to users.
+- Assign permissions by creating relations that users get through other relations.
 
 For example:
 
@@ -43,20 +43,19 @@ For example:
 
 There are advantages to implementing roles and permissions within <ProductName format={ProductNameFormat.ShortForm}/>, such as:
 
-- Breaking down existing roles to have more fine grained permissions. This allows your application to check whether a _user_ has access to a certain object without having to explicitly check that specific _users_ role.
-- Introduce new roles/permissions or consolidate roles without affecting your application behavior. For example: if in your app all the checks are for the fine permissions `check('bob', 'booking_adder', 'trip:Europe')` instead of `check('bob', 'owner', 'trip:Europe')`, and then you later decide `owners` can no longer add bookings to a `trip`, you can remove the relation within the `trip` type with no code changes in your application, and all the permissions will automatically honor the change.
+- Breaking down existing roles to have more fine grained permission, which enables your application to check whether a user has access to a certain object without having to explicitly check that specific user's role.
+- Introduce new roles/permissions or consolidate roles without affecting your application behavior. For example: if your app's checks are for the fine permissions `check('bob', 'booking_adder', 'trip:Europe')` instead of `check('bob', 'owner', 'trip:Europe')`, and you later decide `owners` can no longer add bookings to a `trip`, you can remove the relation within the `trip` type with no code changes in your application, and all the permissions will automatically honor the change.
 
 </CardBox>
 
 ## Before you start
 
-In order to understand this guide correctly you must be familiar with some <ProductConcept /> and know how to develop the things that we will list below.
+Familiarize yourself with the <ProductConcept />.
 
 <details>
 <summary>
 
-Assume that you have the following <ProductConcept section="what-is-an-authorization-model" linkName="authorization model" />.<br />
-You have a <ProductConcept section="what-is-a-type" linkName="type" /> called `trip` that _users_ can be related to as `viewer` and/or an `owner`.
+Assume you have the following <ProductConcept section="what-is-an-authorization-model" linkName="authorization model" /><br /> and that you have a <ProductConcept section="what-is-a-type" linkName="type" /> called `trip` that users can be related to as `viewer` and/or as an `owner`.
 
 </summary>
 
@@ -90,41 +89,41 @@ You have a <ProductConcept section="what-is-a-type" linkName="type" /> called `t
 
 <hr />
 
-In addition, you will need to know the following:
+In addition, you need to know the following:
 
 ### Direct Access
 
-You need to know how to create an authorization model and create a relationship tuple to grant a user access to an object. [Learn more →](./direct-access.mdx)
+Learn how to create an authorization model and create a relationship tuple to grant a user access to an object. For more information, see [Direct Access.](./direct-access.mdx)
 
 ### <ProductName format={ProductNameFormat.ShortForm}/> Concepts
 
 - A <ProductConcept section="what-is-a-type" linkName="Type" />: a class of objects that have similar characteristics
 - A <ProductConcept section="what-is-a-user" linkName="User" />: an entity in the system that can be related to an object
-- A <ProductConcept section="what-is-a-relation" linkName="Relation" />: is a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system
+- A <ProductConcept section="what-is-a-relation" linkName="Relation" />: a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system
 - An <ProductConcept section="what-is-an-object" linkName="Object" />: represents an entity in the system. Users' relationships to it can be define through relationship tuples and the authorization model
-- A <ProductConcept section="what-is-a-relationship-tuple" linkName="Relationship Tuple" />: a grouping consisting of a user, a relation and an object stored in Auth <ProductName format={ProductNameFormat.ShortForm}/>
+- A <ProductConcept section="what-is-a-relationship-tuple" linkName="Relationship Tuple" />: a group consisting of a user, a relation, and an object stored in Auth <ProductName format={ProductNameFormat.ShortForm}/>
 - A <ProductConcept section="what-is-a-relationship" linkName="Relationship" />: <ProductName format={ProductNameFormat.ShortForm}/> will be called to check if there is a relationship between a user and an object, indicating that the access is allowed
 - [Direct Relationship Type Restrictions](../configuration-language.mdx#the-direct-relationship-type-restrictions): can be used to indicate direct relationships between users and objects
-- A <ProductConcept section="what-is-a-check-request" linkName="Check API Request" /> the Check API Request is used to check for relationships between users and objects
+- A <ProductConcept section="what-is-a-check-request" linkName="Check API Request" />: used to check for relationships between users and objects
 
 </details>
 
 <Playground />
 
 ## Step By Step
 
-To illustrate modeling Roles and Permissions in <ProductName format={ProductNameFormat.ShortForm}/>, we will use a trip booking system where you can have `owners` and/or `viewers` that can have more granular permissions such as adding bookings to a trip or viewing bookings on it.
+To illustrate modeling Roles and Permissions in <ProductName format={ProductNameFormat.ShortForm}/>, imagine a trip booking system that has `owners` and/or `viewers`. It can also have granular permissions like adding bookings or viewing bookings on a trip.
 
-In order to represent this, we need to:
+To represent this, you need to:
 
-1. Understand how roles are related to direct relations for our trip booking system
-2. Adding implied relations to existing authorization model to define permissions for bookings
-3. <ProductConcept section="what-is-a-check-request" linkName="Checking" /> user roles and their permissions based on *relationship
-   tuples* for direct and implied relations
+1. Understand how roles are related to direct relations for the trip booking system
+2. Add implied relations to the existing authorization model to define permissions for bookings
+3. <ProductConcept section="what-is-a-check-request" linkName="Check" /> user roles and their permissions based on relationship
+   tuples for direct and implied relations
 
 ### 01. Understand How Roles Work Within Our Trip Booking System
 
-Relating roles within <ProductName format={ProductNameFormat.ShortForm}/> can be best described as the following: **Roles are relations that can be directly assigned to users.** Looking at our authorization model, our roles would then be `owner` and `viewer`. Meaning that a specific _user_ can be an `owner` and/or a `viewer`.
+In <ProductName format={ProductNameFormat.ShortForm}/>, roles are relations that can be directly assigned to users. In this authorization model, your roles are `owner` and `viewer`, so a specific user can be an `owner` and/or a `viewer`.
 
 <AuthzModelSnippetViewer
   configuration={{
@@ -156,13 +155,13 @@ Relating roles within <ProductName format={ProductNameFormat.ShortForm}/> can be
   }}
 />
 
-### 02. Adding Permissions For Bookings
+### 02. Add Permissions For Bookings
 
-Permissions within <ProductName format={ProductNameFormat.LongForm}/> can be best described as the following: **Permissions are relations that users get only through other relations.** To represent permissions, we avoid adding a [**direct relationship type restriction**](../configuration-language.mdx#the-direct-relationship-type-restrictions) to the relation in the authorization model. Instead, we define the relation from other relations to indicate that it is a permission granted to and implied from a different relation.
+In <ProductName format={ProductNameFormat.LongForm}/>, permissions are relations that users get only through other relations. To represent permissions, define the relation by other relations to indicate that it is a permission both granted to and implied from a different relation. Doing so avoids adding a [direct relationship type restriction](../configuration-language.mdx#the-direct-relationship-type-restrictions) to the relation in the authorization model.
 
-To add permissions related to bookings, we can add new relations to the `trip` _object_ type denoting the various actions a user can take on `trips` (view, edit, delete, rename, etc...)
+To add permissions related to bookings, add new relations to the `trip` object type denoting the various actions a user can take on `trips`, like view, edit, or delete.
 
-To allow `viewers` of a `trip` to have **permissions to view bookings** and `owners` to have **permissions to add/view bookings,** we would modify the type as the following:
+To allow `viewers` of a `trip` to view bookings and `owners` to add/view bookings, modify the type as seen below:
 
 <AuthzModelSnippetViewer
   configuration={{
@@ -219,16 +218,16 @@ To allow `viewers` of a `trip` to have **permissions to view bookings** and `own
   }}
 />
 
-> Note: notice how both `booking_viewer` and `booking_adder` don't have [direct relationship type restrictions](../configuration-language.mdx#the-direct-relationship-type-restrictions). This is to ensure that the relation can only be assigned through the **role** and not directly.
+> Note: Both `booking_viewer` and `booking_adder` don't have [direct relationship type restrictions](../configuration-language.mdx#the-direct-relationship-type-restrictions). This ensures that the relation can only be assigned through the role and not directly.
 
 ### 03. Checking User Roles And Their Permissions
 
-Now that our type definitions reflects the roles and permissions on how bookings can be viewed/added. Let's create _<ProductConcept section="what-is-a-relationship-tuple" linkName="relationship tuples" />_ to assign roles to _users_ and then *<ProductConcept section="what-is-a-check-request" linkName="check" />* if _users_ have the proper permissions.
+Now that your type definitions reflect the roles and permissions governing how bookings can be viewed and added, create <ProductConcept section="what-is-a-relationship-tuple" linkName="relationship tuples" /> to assign roles to users, then *<ProductConcept section="what-is-a-check-request" linkName="check" />* if users have the proper permissions.
 
-Let us create two relationship tuples:
+Create two relationship tuples:
 
-1. that gives **bob** the role of `viewer` on `trip`: **Europe**.
-2. that gives **alice** the role of `owner` on `trip`: **Europe**.
+1. gives `bob` the role of `viewer` on `trip:Europe`.
+2. gives `alice` the role of `owner` on `trip:Europe`.
 
 <WriteRequestViewer
   relationshipTuples={[
@@ -247,40 +246,40 @@ Let us create two relationship tuples:
   ]}
 />
 
-Now we can check: **is bob allowed to view bookings on trip Europe?**
+Now check: `is bob allowed to view bookings on trip Europe?`
 
 <CheckRequestViewer user={'user:bob'} relation={'booking_viewer'} object={'trip:Europe'} allowed={true} />
 
-**bob** is a `booking_viewer` because of the following chain of resolution:
+`bob` is a `booking_viewer` because of the following chain of resolution:
 
-1. **bob** is a `viewer` on `trip`: **Europe**
-2. Any user related to the _object_ `trip:`**Europe** as `viewer` is also related as a `booking_viewer` (i.e `usersRelatedToObjectAs: viewer`)
+1. `bob` is a `viewer` on `trip:Europe`
+2. Any user related to the object `trip:Europe` as `viewer` is also related as a `booking_viewer` (i.e `usersRelatedToObjectAs: viewer`)
 3. Therefore, all `viewers` on a given `trip` are `booking_viewers`
 
-To confirm that **bob is not allowed to add bookings on trip Europe**, we can do the following check:
+To confirm that `bob` is not allowed to add bookings on trip `Europe`, perform the following check:
 
 <CheckRequestViewer user={'user:bob'} relation={'booking_adder'} object={'trip:Europe'} allowed={false} />
 
-We can also check: **is alice allowed to view and add bookings on trip Europe?**
+You can also check: is `alice` allowed to view and add bookings on trip `Europe`?
 
 <CheckRequestViewer user={'user:alice'} relation={'booking_viewer'} object={'trip:Europe'} allowed={true} />
 <CheckRequestViewer user={'user:alice'} relation={'booking_adder'} object={'trip:Europe'} allowed={true} />
 
-**alice** is a `booking_viewer` and `booking_adder` because of the following chain of resolution:
+`alice` is a `booking_viewer` and `booking_adder` because of the following chain of resolution:
 
-1. **alice** is a `owner` on `trip`: **Europe**
-2. Any user related to the _object_ `trip:`**Europe** as `owner` is also related as a `booking_viewer`
-3. Any user related to the _object_ `trip:`**Europe** as `owner` is also related as a `booking_adder`
+1. `alice` is a `owner` on `trip:Europe`
+2. Any user related to the _object_ `trip:` `Europe` as `owner` is also related as a `booking_viewer`
+3. Any user related to the _object_ `trip:` `Europe` as `owner` is also related as a `booking_adder`
 4. Therefore, all `owners` on a given `trip` are `booking_viewers` and `booking_adders` on that trip
 
 :::caution
-**Note:** Make sure to use unique ids for each object and user within your application domain when creating relationship tuples for <ProductName format={ProductNameFormat.LongForm}/>. We are using first names and simple ids to just illustrate an easy-to-follow example.
+Note: Use unique IDs for each object and user within your application domain when creating relationship tuples for <ProductName format={ProductNameFormat.LongForm}/>. This guide uses first names and simple IDs as an easy-to-follow example.
 :::
 
 ## Related Sections
 
 <RelatedSection
-  description="Check the following sections for more on how to model for roles and permissions."
+  description="See following sections for more on how to model for roles and permissions."
   relatedLinks={[
     {
       title: 'Modeling Concepts: Concentric Relationships',