Apply suggestions from code review

elf-pavlik · TallTed · web-flow · commit 34624d7428b1 · 2023-11-06T15:38:59.000-06:00
Co-authored-by: Ted Thibodeau Jr &lt;tthibodeau@openlinksw.com&gt;
diff --git a/proposals/primer/app-authorization-flow.bs b/proposals/primer/app-authorization-flow.bs
@@ -11,24 +11,24 @@
       <tbody>
         <tr>
           <td><b>1</b></td>
-          <td>Alice's finds an Application called Projectron that she'd like
+          <td>Alice finds an Application called Projectron that she'd like
             to use to manage her Projects and Tasks.</td>
         </tr>
         <tr>
           <td><b>2</b></td>
-          <td>Alice authenticates with her WebID to Projectron</td>
+          <td>Alice authenticates to Projectron with her WebID.</td>
         </tr>
         <tr>
           <td><b>3</b></td>
-          <td>Projectron dereferences her WebID and retrieves Authorization Agent from her Identity Profile Document</td>
+          <td>Projectron dereferences her WebID and retrieves Authorization Agent from her WebID Profile Document.</td>
         </tr>
         <tr>
           <td><b>4</b></td>
-          <td>Projectron asks Alice's Authorization Agent if Alice already has an Application Registration for Projectron</td>
+          <td>Projectron asks Alice's Authorization Agent whether Alice already has an Application Registration for Projectron.</td>
         </tr>
         <tr>
           <td><b>5</b></td>
-          <td>Alice's Authorization Agent checks the Agent Registry in Alice's Pod for a Projectron Application Registration</td>
+          <td>Alice's Authorization Agent checks the Agent Registry in Alice's Pod for a Projectron Application Registration.</td>
         </tr>
         <tr>
           <td><b>6</b></td>
@@ -37,13 +37,13 @@
         </tr>
         <tr>
           <td><b>7</b></td>
-          <td>Projectron redirects Alice to her Authorization Agent, supplying its identity for context</td>
+          <td>Projectron redirects Alice to her Authorization Agent, supplying its identifier for context.</td>
         </tr>
         <tr>
           <td><b>8</b></td>
-          <td>Alice's Authorization Agent dereferences the supplied Projectron identity, retrieving Projection's
-          Application profile graph and corresponding Access Need Groups from the Identity Profile Document,
-          as well as <code>hasAuthorizationCallbackEndpoint</code></td>
+          <td>Alice's Authorization Agent dereferences the supplied Projectron identifier, retrieving Projectron's
+          Application profile graph and corresponding Access Need Groups from the WebID Profile Document,
+          as well as <code>hasAuthorizationCallbackEndpoint</code>.</td>
         </tr>
         <tr>
           <td><b>9</b></td>
@@ -52,8 +52,8 @@
         </tr>
         <tr>
           <td><b>10</b></td>
-          <td>Alice's chooses the scope of access that Projectron will receive to the data it has
-          asked for access to via the presented Access Needs.</td>
+          <td>Alice's chooses the scope of access that Projectron will receive, to the data to 
+          which it has asked for access via the presented Access Needs.</td>
         </tr>
         <tr>
           <td><b>11-13</b></td>
@@ -64,23 +64,23 @@
         </tr>
         <tr>
           <td><b>14</b></td>
-          <td>Alice's Authorization Agent redirects her back to Projectron now that the appropriate access has been granted</td>
+          <td>Alice's Authorization Agent redirects her back to Projectron, now that the appropriate access has been granted.</td>
         </tr>
         <tr>
           <td><b>15</b></td>
-          <td>Projectron asks Alice's Authorization Agent again for a Projectron Application Registration</td>
+          <td>Projectron again asks Alice's Authorization Agent for a Projectron Application Registration.</td>
         </tr>
         <tr>
           <td><b>16</b></td>
-          <td>Alice's Authorization Agent finds the newly created Projectron Application Registration in the Agent Registry in Alice's Pod</td>
+          <td>Alice's Authorization Agent finds the newly created Projectron Application Registration in the Agent Registry in Alice's Pod.</td>
         </tr>
         <tr>
           <td><b>17</b></td>
-          <td>Alice's Authorization Agent provides the URI of the Application Registration to Projectron</td>
+          <td>Alice's Authorization Agent provides the URI of the Application Registration to Projectron.</td>
         </tr>
         <tr>
           <td><b>18</b></td>
-          <td>Projectron learns what access it received through the Access Grant in Alice's Projectron Application Registration</td>
+          <td>Projectron learns what access it received through the Access Grant in Alice's Projectron Application Registration.</td>
         </tr>
         <tr>
           <td><b>19</b></td>
diff --git a/proposals/primer/application.bs b/proposals/primer/application.bs
@@ -106,16 +106,16 @@ Details in <a href="https://solid.github.io/data-interoperability-panel/specific
 
 ## User Consent ## {#user-consent}
 
-In case where application hasn't been registered yet it needs to initiate flow with Authorization Agent.
+In cases where an application hasn't been registered yet, it needs to initiate the flow with the Authorization Agent.
 
-After successful flow application will be able to discover its registration.
+After successful flow, the application will be able to discover its registration.
 
 <pre class=include>path: app-authorization-flow.bs</pre>
 
 ## Resource Indication ## {#resource-indication}
 
-In cases where the application has already been registered, and the user wants to
-initiate sharing specific [[#data-instance]], an authorization flow with resource
+When the application has already been registered, and the user wants to
+initiate a sharing-specific [[#data-instance]], an authorization flow with resource
 indication is available.
 
 <pre class=include>path: resource-indication-flow.bs</pre>
diff --git a/proposals/primer/authorization-agent.bs b/proposals/primer/authorization-agent.bs
@@ -255,7 +255,7 @@ another's social agent Authorization Agent. The response will include a link to
 
 An Access Grant groups together all the Data Grants provided for a specific agent.
 
-An Access Grant is immutable, it never gets updated, instead it can be only replaced with a newer Access Grant.
+An Access Grant is immutable — it never gets updated; it can only be replaced, by a newer Access Grant.
 
 <pre class=include>path: data-grant.bs</pre>
 
@@ -296,8 +296,8 @@ It should also assist the user in composing new Access Authorization, taking int
 
 # Sharing resources indicated by the application # {#resource-indication}
 
-In cases where the application has already been registered, and the user wants to
-initiate sharing specific [[#data-instance]], an authorization flow with resource
+When the application has already been registered, and the user wants to
+initiate a sharing-specific [[#data-instance]], an authorization flow with resource
 indication is available.
 
 <pre class=include>path: resource-indication-flow.bs</pre>
diff --git a/proposals/primer/diagrams/application-requests-access-flow.seq.mmd b/proposals/primer/diagrams/application-requests-access-flow.seq.mmd
@@ -3,10 +3,10 @@ sequenceDiagram
     participant Projectron
     participant Authorization Agent
     participant Alice's Pod
-    participant Alice's Identity Document
+    participant Alice's WebID Document
     Note over Projectron: 1. 👩 Alice decides to use Projectron
     Note over Projectron: 2. 👩 Alice authenticates with her WebID
-    Note over Alice's Identity Document,Projectron: 3. Projectron discovers Alice's Authorization Agent in her WebID Document
+    Note over Alice's WebID Document,Projectron: 3. Projectron discovers Alice's Authorization Agent in her WebID Document
     Projectron->>Authorization Agent: 4. Check for Application Registration
     Note over Authorization Agent, Alice's Pod: 5. Searches for Application Registration
     Authorization Agent->>Projectron: 6. No Application Registration Found
diff --git a/proposals/primer/resource-indication-flow.bs b/proposals/primer/resource-indication-flow.bs
@@ -36,8 +36,8 @@
         </tr>
         <tr>
           <td><b>9</b></td>
-          <td>Alice's chooses all the social agents she wants to share the selected project with,
-          as well as modes of access for all selected agents. If the shape tree has references (eg. tasks) she can
+          <td>Alice chooses all the social agents with which she wants to share the selected project,
+          as well as modes of access for all selected agents. If the shape tree has references (e.g., tasks) she can
           also select modes of access for each inherited shape tree.</td>
         </tr>
         <tr>
@@ -47,13 +47,13 @@
         </tr>
         <tr>
           <td><b>12</b></td>
-          <td>Alice's Authorization Agent dereferences the supplied Projectron identity, retrieving Projection's
-          Application profile graph from the Identity Profile Document,
+          <td>Alice's Authorization Agent dereferences the supplied Projectron WebID, retrieving Projection's
+          Application profile graph from the WebID Profile Document,
           to discover the <code>hasAuthorizationCallbackEndpoint</code>.</td>
         </tr>
         <tr>
           <td><b>13</b></td>
-          <td>Alice's Authorization Agent redirects her back to Projectron now that the project has been shared.</td>
+          <td>Alice's Authorization Agent redirects her back to Projectron, now that the project has been shared.</td>
         </tr>
         <tr>
           <td><b>14</b></td>
diff --git a/proposals/specification/application.bs b/proposals/specification/application.bs
@@ -66,7 +66,7 @@ use any resource or subject names.
       <td>hasAuthorizationCallbackEndpoint</td>
       <td>IRI</td>
       <td>URI used to redirect back from [=Authorization Agent=]
-      to the application after completing authorization</td>
+      to the application, after completing authorization</td>
     </tr>
   </tbody>
 </table>
diff --git a/proposals/specification/data-authorization.bs b/proposals/specification/data-authorization.bs
@@ -109,7 +109,7 @@ are processed by the [=Authorization Agent=].
 
 ### Authorization Redirect Endpoint ### {#authorization-redirect-endpoint}
 
-An [=Application=] capable of redirecting, should redirect the user to
+An [=Application=] capable of redirecting, should redirect the user to the
 Authorization Redirect Endpoint advertised by the user's [=Authorization Agent=].
 
 The following query parameters are defined:
