updates to attr guide

pages/spicedb/modeling/attributes.mdx

@@ -3,18 +3,17 @@ import { Callout } from 'nextra/components'
 
 # Attributes
 
-Attributes are a deeply embedded concept in many authorization systems.
 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 or relationships.
+This gives SpiceDB the flexibility to evaluate attributes for access control 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 effects authorization by enabling or disabling something.
+A boolean attribute is an attribute on an object that effects 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.
 
@@ -24,9 +23,7 @@ Feature flag authorization can be enabled with 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 can only view a document if the user is related to the document as viewer and editing is enabled for the document.
-
-In the example below, editing is disabled by default.
-To enable editing for a document, a wildcard relationship that relates all users to the document with the wildcard relation, ```edit_enabled```, must be written.
+To enable document editing in the example below, you need to establish a wildcard relationship that connects all users to the document using the ```edit_enabled``` wildcard relation.
 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```.
 Both are required because ```editor``` and ```edit_enabled``` are [intersected](/spicedb/concepts/schema#-intersection) at the ```edit``` permission definition.
 
@@ -46,9 +43,8 @@ In practice, relating something to itself toggles something on.
 
 In the example below, there is a schema that enforces the following authorization logic: a user can only view a document if the user is related to the document as viewer and editing is enabled for the document. (this is the same authorization logic used in the wildcard example above)
 
-In the example below, editing is disabled by default.
-To enable editing for a document, a self relationship using the ```edit_enabled``` relation must be written.
-When a ```document``` is related to itself with the ```edit_enabled``` relation, that relation can be walked (with the arrow) to determine who relates to the document as an ```editor```.
+In the example below, to enable editing for a document, a self relationship using the ```edit_enabled``` relation must be written.
+When a ```document``` is related to itself with the ```edit_enabled``` relation, that relation can be walked to itself (with the arrow) to determine who relates to the document as an ```editor```.
 
 In summary, a ```user``` has permission to edit a ```document``` if they are related to that document as an ```editor``` and that document is related to itself with ```edit_enabled```.
 
@@ -69,7 +65,7 @@ Attribute matching can be achieved by relating a user to an attribute as a "memb
 
 In the example below, users must match **at least one** of the document's country attributes in order to view the document.
 
-Countries are represented with the ```country``` object and every user that has a specific country attribute is related to the specific country.
+Country attributes are represented by the ```country``` object definition and every user that has a specific country attribute is related to the specific country.
 When a ```document``` has a country attribute that can grant ```edit``` permission for a user, it is related to that country.
 
 <InlinePlayground reference="RAl67nbN8HXr" />
@@ -78,7 +74,7 @@ When a ```document``` has a country attribute that can grant ```edit``` permissi
 
 It's possible to specify that ***all*** attributes must be satisfied by using an [intersection arrow](/spicedb/concepts/schema#all-intersection-arrow).
 
-In the example below, users must match **all** of the document's country attributes in order to view the document.
+In the example below, users must match **all** of the document's ```country``` attributes in order to view the document.
 
 This example is similar to the one above, except it requires that all attributes are satisfied instead of at least one attribute.
 
@@ -92,12 +88,16 @@ When you have several types of attributes, it's recommended that you have an obj
 
 ### Match All Attributes from Each Type of Attribute
 
-To do this, you can define multiple types on the same relation and use intersection arrows.
+It's possible to specify that ***all*** attributes must be satisfied by using an [intersection arrow](/spicedb/concepts/schema#all-intersection-arrow).
+
+In the example below, users must match **all** of the document's ```country``` and ```status``` attributes in order to view the document.
+
+This example is similar to the one above, except it requires that all ```country``` and ```status``` attributes are satisfied instead of at least one attribute of each type.
 
 <InlinePlayground reference="I1-zYgAIAq5E" />
 
 ## Caveats
 
-In almost all cases, [caveats](/spicedb/concepts/caveats) should only be used when the data needed to evaluate the 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 user's home country) can have negative performance impacts.
+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.