Updating docs as per comments

docs/user-guide/federation/index.md

@@ -34,7 +34,7 @@ and cloud providers.
 
 Once we have the control plane setup, we can start creating federation API
 resources.
-Following guides explain some of the resources in detail:
+The following guides explain some of the resources in detail:
 
 * [Events](/docs/user-guide/federation/events/)
 * [Namespaces](/docs/user-guide/federation/namespaces/)

docs/user-guide/federation/replicasets.md

@@ -1,7 +1,7 @@
 ---
 ---
 
-This guide explains how to use replicasets in Federation control plane.
+This guide explains how to use replicasets in the Federation control plane.
 
 
 * TOC
@@ -25,7 +25,7 @@ general and [Replicasets](/docs/user-guide/replicasets/) in particular.
 
 Replicasets in federation control plane (referred to as "federated replicasets" in
 this guide) are very similar to the traditional [Kubernetes
-Replicasets](/docs/user-guide/replicasets/) providing the same functionality.
+Replicasets](/docs/user-guide/replicasets/), and provide the same functionality.
 Creating them in the federation control plane ensures that the desired number of
 replicas exist across the registered clusters.
 
@@ -36,7 +36,7 @@ The API for Federated Replicaset is 100% compatible with the
 API for traditional Kubernetes Replicaset. You can create a replicaset by sending
 a request to the federation apiserver.
 
-You can do that using kubectl by running:
+You can do that using [kubectl](/docs/user-guide/kubectl/kubectl/) by running:
 
 ``` shell
 kubectl --context=federation-cluster create -f myrs.yaml
@@ -70,28 +70,28 @@ if you have 3 registered clusters and you create a federated replicaset with
 `spec.replicas=3`.
 To modify the number of replicas in each cluster, you can specify
 [FederatedReplicaSetPreference](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/federation/apis/federation/types.go)
-as annotation with key `federation.kubernetes.io/replica-set-preferences`
+as an annotation with key `federation.kubernetes.io/replica-set-preferences`
 on federated replicaset.
 
 
 ## Updating a Federated Replicaset
 
 You can update a federated replicaset as you would update a Kubernetes
-replicaset, just send the request to federation apiserver instead of sending it
-to a specific kubernetes cluster.
-Federation control plan will ensure that whenever the federated replicaset is
+replicaset; however, for a federated replicaset, you must send the request to
+the federation apiserver instead of sending it to a specific Kubernetes cluster.
+The Federation control plan ensures that whenever the federated replicaset is
 updated, it updates the corresponding replicasets in all underlying clusters to
 match it.
-If your update includes a change in number of replicas then the federation
+If your update includes a change in number of replicas, the federation
 control plane will change the number of replicas in underlying clusters to
 ensure that their sum remains equal to the number of desired replicas in
 federated replicaset.
 
 ## Deleting a Federated Replicaset
 
 You can delete a federated replicaset as you would delete a Kubernetes
-replicaset, just send the request to federation apiserver instead of sending it
-to a specific kubernetes cluster.
+replicaset; however, for a federated replicaset, you must send the request to
+the federation apiserver instead of sending it to a specific Kubernetes cluster.
 
 For example, you can do that using kubectl by running:
 
@@ -101,5 +101,5 @@ kubectl --context=federation-cluster delete rs myrs
 
 Note that at this point, deleting a federated replicaset will not delete the
 corresponding replicasets from underlying clusters.
-Users are expected to delete them manually.
+You must delete the underlying ReplicaSets manually.
 We intend to fix this in the future.

docs/user-guide/federation/secrets.md

@@ -36,7 +36,7 @@ The API for Federated Secret is 100% compatible with the
 API for traditional Kubernetes Secret. You can create a secret by sending
 a request to the federation apiserver.
 
-You can do that using kubectl by running:
+You can do that using [kubectl](/docs/user-guide/kubectl/kubectl/) by running:
 
 ``` shell
 kubectl --context=federation-cluster create -f mysecret.yaml
@@ -63,17 +63,17 @@ These secrets in underlying clusters will match the federated secret.
 ## Updating a Federated Secret
 
 You can update a federated secret as you would update a Kubernetes
-secret, just send the request to federation apiserver instead of sending it
-to a specific kubernetes cluster.
-Federation control plan will ensure that whenever the federated secret is
+secret; however, for a federated secret, you must send the request to
+the federation apiserver instead of sending it to a specific Kubernetes cluster.
+The Federation control plan ensures that whenever the federated secret is
 updated, it updates the corresponding secrets in all underlying clusters to
 match it.
 
 ## Deleting a Federated Secret
 
 You can delete a federated secret as you would delete a Kubernetes
-secret, just send the request to federation apiserver instead of sending it
-to a specific kubernetes cluster.
+secret; however, for a federated secret, you must send the request to
+the federation apiserver instead of sending it to a specific Kubernetes cluster.
 
 For example, you can do that using kubectl by running:
 
@@ -83,5 +83,5 @@ kubectl --context=federation-cluster delete rs myrs
 
 Note that at this point, deleting a federated secret will not delete the
 corresponding secrets from underlying clusters.
-Users are expected to delete them manually.
+You must delete the underlying secrets manually.
 We intend to fix this in the future.