fix: best practices & attributes

Author: miparnisari

app/best-practices/page.mdx

@@ -105,15 +105,14 @@ You should be testing the logic of your schema to ensure that it behaves the way
 Tags: **schema**
 
 If an authorization concept can be expressed using relations, it should be.
-We provide caveats as an escape hatch; they should only be used for context that’s only available at request time, or else ABAC logic that cannot be expressed in terms of relationships.
+We provide caveats as an escape hatch; they should only be used for context that’s only available at request time, or for ABAC logic that cannot be expressed in terms of relationships.
 
-This is because caveats come with a performance penalty.
-A caveated relationship is both harder to cache and also slows down computation of the graph walk required to compute a permission.
+This is because caveats come with a performance penalty: a caveated relationship is both harder to cache and also slows down computation of the graph walk required to compute a permission.
 
 Some examples:
 
-- A banlist - this could be expressed as a list in caveat context, but it can also be expressed as a relation with negation.
-- A notion of public vs internal - boolean flags seem like an obvious caveat use case, but they can also be expressed using self relations.
+- A banlist - this could be expressed as a list in caveat context, but it can also be expressed as a relation with [exclusion](https://authzed.com/docs/spicedb/concepts/schema#--exclusion).
+- A notion of public vs internal - boolean flags seem like an obvious caveat use case, but they can also be expressed using [self relationships](https://authzed.com/docs/spicedb/modeling/attributes#self-relationships).
 - Dynamic roles - these could be expressed as a list in caveats, and it’s not immediately obvious how to build them into a SpiceDB schema, but our [Google Cloud IAM example](https://authzed.com/blog/google-cloud-iam-modeling) shows how it’s possible.
 
 ### Make Your Writes Idempotent

app/spicedb/modeling/attributes/page.mdx

@@ -5,21 +5,19 @@ import { Callout } from "nextra/components";
 
 If you are migrating to SpiceDB from a pre-existing authorization system, it's likely that attributes play a part in your authorization evaluations.
 
-SpiceDB is a Relationship Based Access control system.
-This gives SpiceDB the flexibility to evaluate attributes for access control alongside more complicated access control logic like roles and/or relationships.
+SpiceDB can evaluate attributes for access control decisions alongside more complicated access control logic like roles and/or relationships.
 
 The sections below will provide practical examples for implementing various kinds of attributes in the SpiceDB schema language.
 Before reading this guide, it's recommended that you have some familiarity with the SpiceDB schema language. [These documents](/spicedb/modeling/developing-a-schema) are a good place to start.
 
 ## Boolean Attributes
 
-A boolean attribute is an attribute on an object that affects authorization by enabling or disabling an authorization setting.
-Boolean attributes can often be thought of as a toggle.
-Feature flag authorization can be enabled with boolean attributes.
+A boolean or binary attribute is an attribute on an object that can affect authorization.
+Boolean attributes can often be thought of as a toggle. For example, feature flag authorization can be enabled with boolean attributes.
 
 ### Wildcards
 
-[Wildcards](/spicedb/concepts/schema#wildcards) are a way to implement boolean attributes.
+[Wildcards](/spicedb/concepts/schema#wildcards) are one way to implement boolean attributes.
 Wildcards modify a type so that a relationship can be written to all objects of a resource type but not individual objects.
 
 In the example below, the schema enforces the following authorization logic: a user will have `edit` permission on the document if they are related to the document as an `editor` and they relate to the document through `edit_enabled`.
@@ -54,9 +52,10 @@ In summary, a `user` has permission to edit a `document` if they are related to
 <Callout type="warning">
   There is no mechanism in the SpiceDB schema language that enforces that a
   relation be used as a self relation. In order to avoid accidentally misusing a
-  self relation (e.g. relating an object to a different instance of the same
-  type) it is recommended to implement client side logic that enforces only
-  using the self relation for it's intended purpose.
+  self relation (e.g. by writing the relationship
+  `document:1#edit_enabled@document:2`) it is recommended to implement client
+  side logic that enforces only using the self relation for its intended
+  purpose.
 </Callout>
 
 ## Attribute Matching
@@ -104,4 +103,4 @@ This example is similar to the one above, except it requires that all `country`
 
 In almost all cases, [caveats](/spicedb/concepts/caveats) should only be used when data required to evaluate a CheckPermission request is only available at the time of the request (e.g. user's current location or time of day).
 Using caveats for static data (e.g. a document's status) can have negative performance impacts.
-Static attribute data should always be modeled in the schema using patterns similar to those described above.
+Static attribute data should always be modeled in the schema using the patterns described above.