doc: eschew "you" for current docs

Documentation/branch_management.md

@@ -13,7 +13,7 @@ The etcd team has adopted a *rolling release model* and supports one stable vers
 
 The `master` branch is our development branch. All new features land here first.
 
-If you want to try new features, pull `master` and play with it. Note that `master` may not be stable because new features may introduce bugs.
+To try new and experimental features, pull `master` and play with it. Note that `master` may not be stable because new features may introduce bugs.
 
 Before the release of the next stable version, feature PRs will be frozen. We will focus on the testing, bug-fix and documentation for one to two weeks.
 

Documentation/dev-internal/discovery_protocol.md

@@ -26,7 +26,7 @@ UUID=$(uuidgen)
 
 ### Specifying the Expected Cluster Size
 
-You need to specify the expected cluster size for this discovery token. The size is used by the discovery service to know when it has found all members that will initially form the cluster.
+The discovery token expects a cluster size that must be specified. The size is used by the discovery service to know when it has found all members that will initially form the cluster.
 
 ```
 curl -X PUT http://example.com/v2/keys/_etcd/registry/${UUID}/_config/size -d value=${cluster_size}
@@ -36,7 +36,7 @@ Usually the cluster size is 3, 5 or 7. Check [optimal cluster size][cluster-size
 
 ### Bringing up etcd Processes
 
-Now that you have your discovery URL, you can use it as `-discovery` flag and bring up etcd processes. Every etcd process will follow this next few steps internally if given a `-discovery` flag.
+Given the discovery URL, use it as `-discovery` flag and bring up etcd processes. Every etcd process will follow this next few steps internally if given a `-discovery` flag.
 
 ### Registering itself
 
@@ -102,11 +102,11 @@ The generation process in the service follows the steps from [Creating a New Dis
 GET /${UUID}
 ```
 
-You can check the status for this discovery token, including the machines that have been registered, by requesting the value of the UUID.
+The status for this discovery token, including the machines that have been registered, can be checked by requesting the value of the UUID.
 
 ### Open-source repository
 
-The repository is located at https://github.com/coreos/discovery.etcd.io. You could use it to build your own public discovery service.
+The repository is located at https://github.com/coreos/discovery.etcd.io. It could be used to build a custom discovery service.
 
 [api]: ../v2/api.md#waiting-for-a-change
 [cluster-size]: ../v2/admin_guide.md#optimal-cluster-size

Documentation/dev-internal/release.md

@@ -2,7 +2,7 @@
 
 The guide talks about how to release a new version of etcd.
 
-The procedure includes some manual steps for sanity checking but it can probably be further scripted. Please keep this document up-to-date if you want to make changes to the release process. 
+The procedure includes some manual steps for sanity checking but it can probably be further scripted. Please keep this document up-to-date if making changes to the release process. 
 
 ## Prepare Release
 

Documentation/dl_build.md

@@ -10,7 +10,7 @@ The easiest way to get etcd is to use one of the pre-built release binaries whic
 
 ## Build the Latest Version
 
-For those wanting to try the very latest version, you can build the latest version of etcd from the `master` branch.
+For those wanting to try the very latest version, build etcd from the `master` branch.
 [Go](https://golang.org/) version 1.5+ is required to build the latest version of etcd.
 
 Here are the commands to build an etcd binary from the `master` branch:
@@ -33,7 +33,7 @@ $ ./bin/etcd
 ...
 ```
 
-## Test your Installation
+## Test the installation
 
 Check the etcd binary is built correctly by starting etcd and setting a key.
 
@@ -53,4 +53,4 @@ OK
 If OK is printed, then etcd is working!
 
 [github-release]: https://github.com/coreos/etcd/releases/
-[go]: https://golang.org/doc/install
+[go]: https://golang.org/doc/install

Documentation/docs.md

@@ -4,11 +4,11 @@ etcd is a distributed key-value store designed to reliably and quickly preserve
 
 ## Getting started
 
-New etcd users and developers should get started by [downloading and building][download_build] etcd. Once you have etcd, follow this [quick demo][demo] to see the basics of creating and working with an etcd cluster.
+New etcd users and developers should get started by [downloading and building][download_build] etcd. After getting etcd, follow this [quick demo][demo] to see the basics of creating and working with an etcd cluster.
 
 ## Developing with etcd
 
-The easiest way to get started using etcd as a distributed key-value store for your applications is to [set up a local cluster][local_cluster].
+The easiest way to get started using etcd as a distributed key-value store is to [set up a local cluster][local_cluster].
 
  - [Setting up local clusters][local_cluster]
  - [Interacting with etcd][interacting]

Documentation/op-guide/clustering.md

@@ -2,9 +2,9 @@
 
 ## Overview
 
-Starting an etcd cluster statically requires that each member knows another in the cluster. In a number of cases, you might not know the IPs of your cluster members ahead of time. In these cases, you can bootstrap an etcd cluster with the help of a discovery service.
+Starting an etcd cluster statically requires that each member knows another in the cluster. In a number of cases, the IPs of the cluster members may be unknown ahead of time. In these cases, the etcd cluster can be bootstrapped with the help of a discovery service.
 
-Once an etcd cluster is up and running, adding or removing members is done via [runtime reconfiguration][runtime-conf]. To better understand the design behind runtime reconfiguration, we suggest you read [the runtime configuration design document][runtime-reconf-design].
+Once an etcd cluster is up and running, adding or removing members is done via [runtime reconfiguration][runtime-conf]. To better understand the design behind runtime reconfiguration, we suggest reading [the runtime configuration design document][runtime-reconf-design].
 
 This guide will cover the following mechanisms for bootstrapping an etcd cluster:
 
@@ -36,11 +36,11 @@ ETCD_INITIAL_CLUSTER_STATE=new
 
 Note that the URLs specified in `initial-cluster` are the _advertised peer URLs_, i.e. they should match the value of `initial-advertise-peer-urls` on the respective nodes.
 
-If you are spinning up multiple clusters (or creating and destroying a single cluster) with same configuration for testing purpose, it is highly recommended that you specify a unique `initial-cluster-token` for the different clusters. By doing this, etcd can generate unique cluster IDs and member IDs for the clusters even if they otherwise have the exact same configuration. This can protect you from cross-cluster-interaction, which might corrupt your clusters.
+If spinning up multiple clusters (or creating and destroying a single cluster) with same configuration for testing purpose, it is highly recommended that each cluster is given a unique `initial-cluster-token`. By doing this, etcd can generate unique cluster IDs and member IDs for the clusters even if they otherwise have the exact same configuration. This can protect etcd from cross-cluster-interaction, which might corrupt the clusters.
 
-etcd listens on [`listen-client-urls`][conf-listen-client] to accept client traffic. etcd member advertises the URLs specified in [`advertise-client-urls`][conf-adv-client] to other members, proxies, clients. Please make sure the `advertise-client-urls` are reachable from intended clients. A common mistake is setting `advertise-client-urls` to localhost or leave it as default when you want the remote clients to reach etcd.
+etcd listens on [`listen-client-urls`][conf-listen-client] to accept client traffic. etcd member advertises the URLs specified in [`advertise-client-urls`][conf-adv-client] to other members, proxies, clients. Please make sure the `advertise-client-urls` are reachable from intended clients. A common mistake is setting `advertise-client-urls` to localhost or leave it as default if the remote clients should reach etcd.
 
-On each machine you would start etcd with these flags:
+On each machine, start etcd with these flags:
 
 ```
 $ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \
@@ -70,7 +70,7 @@ $ etcd --name infra2 --initial-advertise-peer-urls http://10.0.1.12:2380 \
   --initial-cluster-state new
 ```
 
-The command line parameters starting with `--initial-cluster` will be ignored on subsequent runs of etcd. You are free to remove the environment variables or command line flags after the initial bootstrap process. If you need to make changes to the configuration later (for example, adding or removing members to/from the cluster), see the [runtime configuration][runtime-conf] guide.
+The command line parameters starting with `--initial-cluster` will be ignored on subsequent runs of etcd. Feel free to remove the environment variables or command line flags after the initial bootstrap process. If the configuration needs changes later (for example, adding or removing members to/from the cluster), see the [runtime configuration][runtime-conf] guide.
 
 ### TLS
 
@@ -190,7 +190,7 @@ etcd: error setting up initial cluster: infra0 has different advertised URLs in
 exit 1
 ```
 
-If you configure a peer with a different set of configuration and attempt to join this cluster you will get a cluster ID mismatch and etcd will exit.
+If a peer is configured with a different set of configuration arguments and attempts to join this cluster, etcd will report a cluster ID mismatch will exit.
 
 ```
 $ etcd --name infra3 --initial-advertise-peer-urls http://10.0.1.13:2380 \
@@ -205,7 +205,7 @@ exit 1
 
 ## Discovery
 
-In a number of cases, you might not know the IPs of your cluster peers ahead of time. This is common when utilizing cloud providers or when your network uses DHCP. In these cases, rather than specifying a static configuration, you can use an existing etcd cluster to bootstrap a new one. We call this process "discovery".
+In a number of cases, the IPs of the cluster peers may not be known ahead of time. This is common when utilizing cloud providers or when the network uses DHCP. In these cases, rather than specifying a static configuration, use an existing etcd cluster to bootstrap a new one. We call this process "discovery".
 
 There two methods that can be used for discovery:
 
@@ -214,25 +214,25 @@ There two methods that can be used for discovery:
 
 ### etcd Discovery
 
-To better understand the design about discovery service protocol, we suggest you read [this][discovery-proto].
+To better understand the design about discovery service protocol, we suggest reading the discovery service protocol [documentation][discovery-proto].
 
 #### Lifetime of a Discovery URL
 
-A discovery URL identifies a unique etcd cluster. Instead of reusing a discovery URL, you should always create discovery URLs for new clusters.
+A discovery URL identifies a unique etcd cluster. Instead of reusing a discovery URL, always create discovery URLs for new clusters.
 
 Moreover, discovery URLs should ONLY be used for the initial bootstrapping of a cluster. To change cluster membership after the cluster is already running, see the [runtime reconfiguration][runtime-conf] guide.
 
 #### Custom etcd Discovery Service
 
-Discovery uses an existing cluster to bootstrap itself. If you are using your own etcd cluster you can create a URL like so:
+Discovery uses an existing cluster to bootstrap itself. If using a private etcd cluster, can create a URL like so:
 
 ```
 $ curl -X PUT https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83/_config/size -d value=3
 ```
 
-By setting the size key to the URL, you create a discovery URL with an expected cluster size of 3.
+By setting the size key to the URL, a discovery URL is created with an expected cluster size of 3.
 
-The URL you will use in this case will be `https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83` and the etcd members will use the `https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83` directory for registration as they start.
+The URL to use in this case will be `https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83` and the etcd members will use the `https://myetcd.local/v2/keys/discovery/6c007a14875d53d9bf0ef5a6fc0257c817f0fb83` directory for registration as they start.
 
 **Each member must have a different name flag specified. `Hostname` or `machine-id` can be a good choice. Or discovery will fail due to duplicated name.**
 
@@ -264,14 +264,14 @@ This will cause each member to register itself with the custom etcd discovery se
 
 #### Public etcd Discovery Service
 
-If you do not have access to an existing cluster, you can use the public discovery service hosted at `discovery.etcd.io`.  You can create a private discovery URL using the "new" endpoint like so:
+If no exiting cluster is available, use the public discovery service hosted at `discovery.etcd.io`.  To create a private discovery URL using the "new" endpoint, use the command:
 
 ```
 $ curl https://discovery.etcd.io/new?size=3
 https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de
 ```
 
-This will create the cluster with an initial expected size of 3 members. If you do not specify a size, a default of 3 will be used.
+This will create the cluster with an initial expected size of 3 members. If no size is specified, a default of 3 is used.
 
 ```
 ETCD_DISCOVERY=https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de
@@ -309,7 +309,7 @@ $ etcd --name infra2 --initial-advertise-peer-urls http://10.0.1.12:2380 \
 
 This will cause each member to register itself with the discovery service and begin the cluster once all members have been registered.
 
-You can use the environment variable `ETCD_DISCOVERY_PROXY` to cause etcd to use an HTTP proxy to connect to the discovery service.
+Use the environment variable `ETCD_DISCOVERY_PROXY` to cause etcd to use an HTTP proxy to connect to the discovery service.
 
 #### Error and Warning Cases
 
@@ -328,8 +328,7 @@ exit 1
 
 ##### Warnings
 
-This is a harmless warning notifying you that the discovery URL will be
-ignored on this machine.
+This is a harmless warning indicating the discovery URL will be ignored on this machine.
 
 ```
 $ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \
@@ -420,7 +419,7 @@ $ etcd --name infra2 \
 --listen-peer-urls http://infra2.example.com:2380
 ```
 
-You can also bootstrap the cluster using IP addresses instead of domain names:
+The cluster can also bootstrap using IP addresses instead of domain names:
 
 ```
 $ etcd --name infra0 \

Documentation/op-guide/configuration.md

@@ -14,7 +14,7 @@ To start etcd automatically using custom settings at startup in Linux, using a [
 + Human-readable name for this member.
 + default: "default"
 + env variable: ETCD_NAME
-+ This value is referenced as this node's own entries listed in the `--initial-cluster` flag (e.g., `default=http://localhost:2380`). This needs to match the key used in the flag if you're using [static bootstrapping][build-cluster]. When using discovery, each member must have a unique name. `Hostname` or `machine-id` can be a good choice.
++ This value is referenced as this node's own entries listed in the `--initial-cluster` flag (e.g., `default=http://localhost:2380`). This needs to match the key used in the flag if using [static bootstrapping][build-cluster]. When using discovery, each member must have a unique name. `Hostname` or `machine-id` can be a good choice.
 
 ### --data-dir
 + Path to the data directory.
@@ -59,13 +59,13 @@ To start etcd automatically using custom settings at startup in Linux, using a [
 + Maximum number of snapshot files to retain (0 is unlimited)
 + default: 5
 + env variable: ETCD_MAX_SNAPSHOTS
-+ The default for users on Windows is unlimited, and manual purging down to 5 (or your preference for safety) is recommended.
++ The default for users on Windows is unlimited, and manual purging down to 5 (or some preference for safety) is recommended.
 
 ### --max-wals
 + Maximum number of wal files to retain (0 is unlimited)
 + default: 5
 + env variable: ETCD_MAX_WALS
-+ The default for users on Windows is unlimited, and manual purging down to 5 (or your preference for safety) is recommended.
++ The default for users on Windows is unlimited, and manual purging down to 5 (or some preference for safety) is recommended.
 
 ### --cors
 + Comma-separated white list of origins for CORS (cross-origin resource sharing).
@@ -108,7 +108,7 @@ To start etcd automatically using custom settings at startup in Linux, using a [
 + default: "http://localhost:2379"
 + env variable: ETCD_ADVERTISE_CLIENT_URLS
 + example: "http://example.com:2379, http://10.0.0.1:2379"
-+ Be careful if you are advertising URLs such as http://localhost:2379 from a cluster member and are using the proxy feature of etcd. This will cause loops, because the proxy will be forwarding requests to itself until its resources (memory, file descriptors) are eventually depleted.
++ Be careful if advertising URLs such as http://localhost:2379 from a cluster member and are using the proxy feature of etcd. This will cause loops, because the proxy will be forwarding requests to itself until its resources (memory, file descriptors) are eventually depleted.
 
 ### --discovery
 + Discovery URL used to bootstrap the cluster.
@@ -171,7 +171,7 @@ To start etcd automatically using custom settings at startup in Linux, using a [
 
 ### --proxy-read-timeout
 + Time (in milliseconds) for a read to timeout or 0 to disable the timeout.
-+ Don't change this value if you use watches because they are using long polling requests.
++ Don't change this value if using watches because use long polling requests.
 + default: 0
 + env variable: ETCD_PROXY_READ_TIMEOUT