add estroz suggestions

Co-authored-by: Eric Stroczynski <[email protected]>

Author: jberkhahn

website/content/en/docs/building-operators/golang/crds-scope.md

@@ -6,33 +6,32 @@ weight: 60
 
 ## Overview
 
+This page details the various methods to control the scope of a CRD. See the [operator scope doc](/docs/building-operators/golang/operator-scope/) for information on configuring operator scope, such as which namespaces to watch.
+
 Custom Resource Definitions (CRDs) contain a scope field that determines whether the resulting Custom Resource (CR)
-is cluster or namespace scoped. Operators can be built using this feature that then are available either on the entire cluster,
-or only in one or more namespaces. This might be done for several reasons: an operator author might use a namespaced-scoped operator
-to restrict access to a CR to a single namespace, or  to have different versions of similar CRs accessible in different namespaces.
-Alternatively, an operator author might want a cluster-scoped operator so all users can see and use a single operator.:
-This page details the various methods to control the scope of an operator.
+is cluster or namespace scoped. An operator author might use a namespaced-scoped CRD
+to restrict access to a CR to certain namespaces, or to have different versions of CRs accessible in different namespaces.
+Alternatively, an operator author might want a cluster-scoped CRD so all namespaces have visibility and access to CRs.
 
-The CRD manifests are generated by operator-sdk in `config/crd/bases`. The `spec.scope` field can be set to `Cluster` or `Namespaced`
-to determine how the CR will be scoped. For further information on this field, see [the core k8s CRD docs][k8s_crd_scope].
-For an Operator-sdk Golang project, this can be done by setting `--namespaced` when creating the api, by editing the Golang
-`types.go` file for the resource, or by editing the YAML manifest for the CRD.
+The CRD manifests are generated by the `operator-sdk create api` command in `config/crd/bases`. A CRD's `spec.scope` field controls API scope; valid values are [`Cluster` and `Namespaced`](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#create-a-customresourcedefinition).
+For an Operator-sdk Go project, this value is determined by the `operator-sdk create api --namespaced` boolean flag, which edits the
+`types.go` file for the resource. For other operator types, the command edits `spec.scope` in the CRD's YAML manifest directly.
 
 ## Set `create api` --namespaced flag
 
-When creating a new API, the `--namespaced` flag controls whether the resulting Custom Resource will be cluster or namespace scoped.
-By default, `--namespaced` is set to `true`. An example command to create a cluster-scoped API would be:
+When creating a new API, the `--namespaced` flag controls whether the resulting CRD will be cluster or namespace scoped.
+By default, `--namespaced` is set to `true` which sets the scope to `Namespaced`. An example command to create a cluster-scoped API would be:
 
-```bash
+```console
 $ operator-sdk create api --group cache --version v1alpha1 --kind Memcached --resource=true --controller=true --namespaced=false
 ```
 
 ## Set Scope Marker in types.go
 
-You can also manually set the scope in the Golang types.go file by adding a [kubebuilder scope marker][kubebuilder_crd_markers]
+You can also manually set the scope in the Go `types.go` file by adding or changing the [kubebuilder scope marker][kubebuilder_crd_markers]
 to your resource. This file is usually located in `api/<version>/<kind>_types.go` or `apis/<group>/<version>/<kind>_types.go` if
 you are using the [multigroup][multigroup-kubebuilder-doc] layout. Once this marker is set, the CRD files will be generated with the approriate scope.
-Here is an example memcached type with the marker set to cluster scope:
+Here is an example API type with the marker set to cluster scope:
 
 ```golang
 //+kubebuilder:object:root=true
@@ -50,15 +49,10 @@ type Memcached struct {
 ```
 To set the scope to namespaced, the marker would be set to `//+kubebuilder:resource:scope=Namespace` instead.
 
-**NOTE**: When a Manager instance is created in the `main.go` file, it receives the namespace(s) as Options. 
-These namespace(s) should be watched and cached for the Client which is provided by the Controllers. Only clients 
-provided by cluster-scoped projects where the `Namespace` attribute is `""` will be able to manage cluster-scoped CRs. 
-For more information see the [Manager][manager_user_guide] topic in the user guide and the 
-[Manager Options][manager_options].
 
 ## Set scope in CRD YAML file
 
-The scope can also be manually set directly in the CRD's Kind YAML file, normally located in  `config/crd/bases/<group>.<domain>_<kind>.yaml`.
+The scope can be manually set directly in the CRD's Kind YAML file, normally located in  `config/crd/bases/<group>.<domain>_<kind>.yaml`.
 An example YAML file for a namespace-scoped CRD is shown below:
 
 ```YAML
@@ -82,10 +76,7 @@ spec:
 ...   
 ``` 
 
-**NOTE** This file will be overwritten if you regenerate the YAML manifests by running `make manifests` and haven't changed the corresponding resources in the types.go file.
-Take care not to unintentionally overwrite your changes.
 
-**NOTE** As above, you must also take care that the Manager in your `main.go` is configured to correctly have access to your resources.
 
 [manager_options]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Options
 [manager_user_guide]:/docs/building-operators/golang/tutorial/#manager