Apply suggestions from code review

Co-authored-by: Tom Papiernik <[email protected]>

docs/keto/guides/userset-rewrites.mdx

@@ -1,5 +1,5 @@
 title: Define file access permissions with userset rewrites
-sidebar_label: Userset Rewrites
+sidebar_label: Userset rewrites
 ---
 
 import Tabs from "@theme/Tabs"
@@ -8,20 +8,20 @@ import CodeFromRemote from "@theme/CodeFromRemote"
 const sha = "fc39b65f8be9b23bbb4e19480706964d61505c5e"
 const file = (path) => `https://github.com/ory/keto/blob/${sha}/contrib/rewrites-example/${path}`
 
-This guide will explain how to configure your your namespaces and relations using the
+This guide explains how to configure namespaces and relations using the
 [Ory Permission Language](../reference/ory-permission-language).
 
-The example describes a file store. Individual files are organized in a folder hierarchy, and can be accessed by users or groups
-of users. Through the Ory Permission Language we can specify that if a user has access to a folder, the user also has access to
+The example describes a file store. Individual files are organized in a folder hierarchy, and can be accessed by individual users or groups
+of users. Using the Ory Permission Language you can specify that if a user has access to a folder, the user also has access to
 all files in that folder.
 
 ## Setup and Configuration
 
-First, [install Keto](../install.mdx). Next, you need the following `keto.yaml` (at `contrib/rewrites-example/keto.yaml`):
+First, [install Keto](../install.mdx). Next, create the `keto.yaml` file and save it at the `contrib/rewrites-example/` path:
 
 <CodeFromRemote src={file("keto.yaml")} />
 
-In the namespaces key, you see the line `config: file://./namespaces.keto.ts`. This needs to point to your namespace configuration
+In the `namespaces` key, you see the line `config: file://./namespaces.keto.ts`. This needs to point to your namespace configuration
 in the Ory Permission Language.
 
 :::info
@@ -31,36 +31,35 @@ Namespace configurations without the Ory Permission Language are still supported
 
 :::
 
-Next, we create a file with our namespace configuration as follows:
+Next, create a file with the namespace configuration:
 
 <CodeFromRemote src={file("namespaces.keto.ts")} />
 
-:::tip Editor support
+:::tip
 
-If you are using a text editor with TypeScript support, you can get extra help when using the Ory Permission Language. Just make
+If you are using a text editor with TypeScript support, you can get extra help when using the Ory Permission Language. Make
 sure that the file `contrib/rewrites-examples/lib.ts` is in the same folder as the file you are editing. It contains all
 definitions to type-check the config.
 
 :::
 
 ### Starting Ory Keto
 
-After you created both configuration files (`keto.yaml` and `namespaces.keto.ts`), you can start Ory Keto with:
+After you created both configuration files (`keto.yaml` and `namespaces.keto.ts`), run this command to start Ory Keto:
 
 ```sh
 $ keto serve --config ./path/to/keto.yaml
 ```
 
 ## Creating the tuples
 
-Now that Ory Keto is running, we can create the tuples through the Keto CLI.
+Now that Ory Keto is running, create relation tuples using the Keto CLI.
 
-We use the following relation tuples to showcase the namespace configuration. In short, it sets up a "developer" group with two
+The following relation tuples showcase the namespace configuration. In short, it sets up a "developer" group with two
 members, and a folder hierarchy. Through the rules in the Ory Permission Language, every member of the "developer" group can
 access the files in the hierarchy.
 
-As usual, it is still possible to create additional fine-grained permission rules for certain objects, as is done for the
-"private" file.
+You can create additional fine-grained permission rules for certain objects, similar to the "private" file.
 
 <CodeFromRemote src={file("relation-tuples/tuples.json")} />
 
@@ -86,8 +85,7 @@ Now, let's check some permissions! Some queries to try:
 
 ### Transitive permissions for objects in the hierarchy
 
-Patrik can view "keto/src/main.go", because it is in the folder "keto/src", which is in the folder "keto", which has as "viewers"
-the group "developer", of which Patrik is a member of.
+Patrik can view `keto/src/main.go`. This file is in the `keto/src` folder, which is in `keto`.  The `keto` directory has the "developer" group as its "viewers".  Patrik is a member of the "developer" group.
 
 ```
 $ keto check User:Patrik view File keto/src/main.go

docs/keto/reference/ory-permission-language.mdx

@@ -3,10 +3,10 @@ title: The "Ory Permission Language" Specification
 ---
 
 Enforcing fine-grained permissions is a critical building block of mature technology solutions that protect privacy and identity
-in the information age. Several proprietary languages to represent permission already exist, namely the Most permissions are
+in the information age. Several proprietary languages used to represent permission already exist, namely the Most permissions are
 defined by developers who are likely familiar with Web technologies like JavaScript or Typescript. There is a need for a
-developer-friendly configuration language for permissions that has such a small learning curve that most developers can understand
-and use it with close to no effort. We therefore chose to define our permissions configuration language as a subset of the most
+developer-friendly configuration language for permissions that has a small learning curve small enough so that most developers can understand
+and use it with minimal effort. To fulfill this need, we defined the permissions configuration language as a subset of the most
 common general-purpose programming language: JavaScript/TypeScript.
 
 The Ory Permission Language is a syntactical subset of TypeScript. Along with type definitions for the syntax elements of the
@@ -158,7 +158,7 @@ ClassDecl       = "class" identifier "implements" "Namespace" "{" ClassSpec "}"
 ClassSpec       = [ RelationDecls ] | [ PermissionDefns] .
 ```
 
-The following example declares the type _User_.
+The following example declares the type `User`.
 
 ```ts
 class User implements Namespace {}
@@ -221,7 +221,7 @@ The `ctx` object is a fixed parameter that contains the `subject` for which the
 ctx = { subject: "some_user_id" }
 ```
 
-The context will contain more fields in the future, e.g., the IP range or geolocation, the time of day, or the security level of
+The context will contain more fields in the future, for example, the IP range or geolocation, the time of day, or the security level of
 the device making the request.
 
 ```ebnf