review feedback from aaron

Signed-off-by: Pete Lumbis <pete@upbound.io>

content/knowledge-base/guides/connection-details.md

@@ -12,7 +12,7 @@ Using connection details in Crossplane requires the following components:
 * Define the list of secret keys produced by each composed resource with `connectionDetails` in the
   [Composition]({{<ref "/master/concepts/compositions#define-secret-keys">}}).
 * Optionally, define the `connectionSecretKeys` in a 
-  [CompositeResourceDefinintion]({{<ref "/master/concepts/composite-resource-definitions#manage-connection-secrets">}}).
+  [CompositeResourceDefinition]({{<ref "/master/concepts/composite-resource-definitions#manage-connection-secrets">}}).
 
 {{<hint "note">}}
 This guide discusses creating Kubernetes secrets.  
@@ -80,6 +80,13 @@ spec:
         - fromConnectionSecretKey: password
         - fromConnectionSecretKey: attribute.secret
         - fromConnectionSecretKey: attribute.ses_smtp_password_v4
+      patches:
+        - fromFieldPath: "metadata.uid"
+          toFieldPath: "spec.writeConnectionSecretToRef.name"
+          transforms:
+            - type: string
+              string:
+                fmt: "%s-secret1"
     - name: user
       base:
         apiVersion: iam.aws.upbound.io/v1beta1
@@ -116,6 +123,13 @@ spec:
           fromConnectionSecretKey: attribute.secret
         - name: key2-smtp
           fromConnectionSecretKey: attribute.ses_smtp_password_v4
+      patches:
+        - fromFieldPath: "metadata.uid"
+          toFieldPath: "spec.writeConnectionSecretToRef.name"
+          transforms:
+            - type: string
+              string:
+                fmt: "%s-secret2"
 ```
 {{</expand >}}
 
@@ -263,7 +277,7 @@ the resource
 Crossplane also creates a secret object for the entire Composition 
 saved in the namespace defined by 
 {{<hover label="comp1" line="4">}}writeConnectionSecretsToNamespace{{</hover>}}
-with an Crossplane generated name. 
+with a Crossplane generated name. 
 
 ```yaml {label="comp1",copy-lines="none"}
 apiVersion: apiextensions.crossplane.io/v1
@@ -449,11 +463,11 @@ key2-user:                       20 bytes
 
 ## Connection secrets in Composite Resource Definitions
 
-The CompositeResourceDefinintion (`XRD`), can restrict which secrets keys are 
+The CompositeResourceDefinition (`XRD`), can restrict which secrets keys are 
 put in the combined secret and provided to a Claim. 
 
-By default an XRD writes all secret keys from the composed resources to the 
-combined secret object.
+By default an XRD writes all secret keys listed in the composed resource 
+`connectionDetails` to the combined secret object.
 
 Limit the keys passed to the combined secret object and Claims with a
 {{<hover label="xrd" line="4">}}connectionSecretKeys{{</hover>}} object.

content/knowledge-base/guides/troubleshoot.md

@@ -12,7 +12,6 @@ indicator that the kubectl Crossplane you're using is outdated. In other words
 some Crossplane API has been graduated from alpha to beta or stable and the old
 plugin is not aware of this change.
 
-You can follow the [install Crossplane CLI] instructions to upgrade the plugin.
 
 ## Resource Status and Conditions
 
@@ -506,7 +505,6 @@ To follow the references:
 
 
 <!-- Named Links -->
-<!-- 
 [Requested Resource Not Found]: #requested-resource-not-found
 [install Crossplane CLI]: "../getting-started/install-configure"
 [Resource Status and Conditions]: #resource-status-and-conditions
@@ -517,8 +515,8 @@ To follow the references:
 [Pausing Providers]: #pausing-providers
 [Deleting When a Resource Hangs]: #deleting-when-a-resource-hangs
 [Installing Crossplane Package]: #installing-crossplane-package
-[Crossplane package]: "../concepts/packages"
+[Crossplane package]: /master/concepts/packages/
 [Handling Crossplane Package Dependency]: #handling-crossplane-package-dependency
-[semver spec]: https://github.com/Masterminds/semver#basic-comparisons -->
+[semver spec]: https://github.com/Masterminds/semver#basic-comparisons
 
 

content/master/concepts/claims.md

@@ -7,7 +7,7 @@ description: "Claims are a way to consume Crossplane resources with namespace sc
 Claims represents a set of managed resources as a single
 Kubernetes object, inside a namespace. 
 
-Crossplane creates Claims when users access a
+Users create claims when they access the
 custom API, defined in the CompositeResourceDefinition. 
 
 {{< hint "tip" >}}
@@ -35,7 +35,7 @@ Crossplane has four core components that users commonly mix up:
 Creating a Claim requires a 
 [Composition]({{<ref "./compositions">}}) and a 
 [CompositeResourceDefinition]({{<ref "./composite-resource-definitions">}}) 
-(`XRD`).  
+(`XRD`) already installed.  
 
 {{<hint "note" >}}
 The XRD must 
@@ -62,7 +62,7 @@ metadata:
 spec:
   group: example.org
   names:
-    kind: xMyDatabase
+    kind: XMyDatabase
     plural: xmydatabases
   claimNames:
     kind: Database
@@ -74,7 +74,7 @@ The Claim uses the XRD's
 {{<hover label="xrd1" line="11">}}kind{{</hover>}} API endpoint to request 
 resources.
 
-The Claim's {{<hover label="claim1CompositeResourceDefinintions" line="1">}}apiVersion{{</hover>}} matches
+The Claim's {{<hover label="xrd1" line="1">}}apiVersion{{</hover>}} matches
 the XRD {{<hover label="xrd1" line="6">}}group{{</hover>}} and the 
 {{<hover label="claim1" line="2">}}kind{{</hover>}} matches the XRD
 {{<hover label="xrd1" line="11">}}claimNames.kind{{</hover>}}
@@ -88,7 +88,7 @@ spec:
   # Removed for brevity
 ```
 
-When Crossplane creates a Claim in a namespace it also creates a composite
+When a user creates a Claim in a namespace Crossplane also creates a composite
 resource.
 
 Use {{<hover label="claimcomp" line="1">}}kubectl describe{{</hover>}} on the 
@@ -105,7 +105,7 @@ Kind:         database
 Spec:
   Resource Ref:
     API Version:  example.org/v1alpha1
-    Kind:         xMyDatabase
+    Kind:         XMyDatabase
     Name:         my-claimed-database-rr4ll
 # Removed for brevity.
 ```
@@ -119,7 +119,7 @@ composite resource to the original Claim.
 kubectl describe xmydatabase.example.org/my-claimed-database-rr4ll
 Name:         my-claimed-database-rr4ll
 API Version:  example.org/v1alpha1
-Kind:         xMyDatabase
+Kind:         XMyDatabase
 Spec:
   Claim Ref:
     API Version:  example.org/v1alpha1
@@ -140,7 +140,7 @@ If you don't use namespaces in your Kubernetes deployment Claims aren't necessar
 By default, creating a Claim creates a new composite resource. Claims can also
 link to existing composite resources. 
 
-A use case for Claiming existing composite resources may be slow to provision
+A use case for claiming existing composite resources may be slow to provision
 resources. Composite resources can be pre-provisioned and a Claim can
 use those resources without waiting for their creation. 
 
@@ -156,14 +156,18 @@ metadata:
 spec:
   resourceRef:
     apiVersion: example.org/v1alpha1
-    kind: xMyDatabase
+    kind: XMyDatabase
     name: my-pre-created-xr
 ```
 
+If a Claim specifies a 
+{{<hover label="resourceref" line="6">}}resourceRef{{</hover>}} that doesn't
+exist, Crossplane doesn't create a composite resource. 
+
 {{<hint "note" >}}
 All Claims have a 
-{{<hover label="resourceref" line="6">}}resourceRef{{</hover>}}. By default,
-manually defining the 
+{{<hover label="resourceref" line="6">}}resourceRef{{</hover>}}. Manually
+defining the 
 {{<hover label="resourceref" line="6">}}resourceRef{{</hover>}}
 isn't required. Crossplane fills in the
 {{<hover label="resourceref" line="6">}}resourceRef{{</hover>}}

content/master/concepts/composite-resource-definitions.md

@@ -38,7 +38,7 @@ connection secrets.
 
 ## Creating a CompositeResourceDefinition
 
-Creating a CompositeResourceDefinintion consists of:
+Creating a CompositeResourceDefinition consists of:
 * [Defining a custom API group](#xrd-groups).
 * [Defining a custom API name](#xrd-names).
 * [Defining a custom API schema and version](#xrd-versions).
@@ -64,7 +64,7 @@ metadata:
 spec:
   group: example.org
   names:
-    kind: xMyDatabase
+    kind: XMyDatabase
     plural: xmydatabases
   versions:
   - name: v1alpha1
@@ -82,10 +82,20 @@ creates a custom resource definition
 ```shell {label="kubeapi",copy-lines="3"}
 kubectl api-resources
 NAME                              SHORTNAMES   APIVERSION          NAMESPACED   KIND
-xmydatabases.example.org                       v1                  false        xmydatabases
+xmydatabases.example.org                       v1alpha1            false        xmydatabases
 # Removed for brevity
 ```
 
+{{<hint "warning">}}
+You can't change the XRD
+{{<hover label="xrd1" line="6">}}group{{</hover>}} or
+{{<hover label="xrd1" line="7">}}names{{</hover>}}.  
+You must delete and
+recreate the XRD to change the 
+{{<hover label="xrd1" line="6">}}group{{</hover>}} or
+{{<hover label="xrd1" line="7">}}names{{</hover>}}.
+{{</hint >}}
+
 ### XRD groups
 
 Groups define a collection of related API endpoints. The `group` can be any
@@ -96,14 +106,20 @@ Many XRDs may use the same `group` to create a logical collection of APIs.
 <!-- vale write-good.Weasel = YES -->
 For example a `database` group may have a `relational` and `nosql` kinds. 
 
+{{<hint "tip" >}}
+Group names are cluster scoped. Choose group names that don't conflict with
+Providers.  
+Avoid Provider names in the group.
+{{< /hint >}}
+
 ### XRD names
 
 The `names` field defines how to refer to this specific XRD.  
 The required name fields are: 
 
 * `kind` - the `kind` value to use when calling this API. The kind is
   [UpperCamelCased](https://kubernetes.io/docs/contribute/style/style-guide/#use-upper-camel-case-for-api-objects).
-  Crossplane recommends starting XRD `kinds` with an `x` to show 
+  Crossplane recommends starting XRD `kinds` with an `X` to show 
   it's a custom Crossplane API definition. 
 * `plural` - the plural name used for the API URL. The plural name must be
   lowercase. 
@@ -129,7 +145,7 @@ metadata:
 spec:
   group: example.org
   names:
-    kind: xMyDatabase
+    kind: XMyDatabase
     plural: xmydatabases
     # Removed for brevity
 ```
@@ -533,8 +549,11 @@ spec:
 ```
 
 {{<hint "important" >}}
-You can't change the `claimNames` after they're defined. You must delete and
-recreate the XRD to change the `claimNames`.
+You can't change the 
+{{<hover label="claim" line="10">}}claimNames{{</hover >}}
+after they're defined. You must delete and
+recreate the XRD to change the 
+{{<hover label="claim" line="10">}}claimNames{{</hover >}}.
 {{</hint >}}
 
 ### Manage connection secrets
@@ -563,7 +582,7 @@ key names listed in the Composition's `connectionDetails`.
 An XRD ignores any keys listed that aren't created by a managed resource.
 
 For more information read the 
-[Composition documentation]({{<ref "./composite-resource-definitions#manage-connection-secrets">}}).
+[Composition documentation]({{<ref "./compositions#storing-connection-details">}}).
 {{< /hint >}}
 
 

content/master/concepts/composite-resources.md

@@ -187,7 +187,7 @@ spec:
 
 ### Composition revision policy
 
-Crossplane records changes to Compositions as 
+Crossplane tracks changes to Compositions as 
 [Composition revisions]({{<ref "/knowledge-base/guides/composition-revisions">}}) . 
 
 A composite resource can use
@@ -417,7 +417,7 @@ managed resources documentation for details.
 
 ## Composite resource labels
 
-Crossplane adds labels to composite resources to indicates their relationship to
+Crossplane adds labels to composite resources to show their relationship to
 other Crossplane components.
 
 ### Composite label