Reworked Go quick start

Author: chalin

content/docs/quickstart/go.md

@@ -7,9 +7,8 @@ description: This guide gets you started with gRPC in Go with a simple working e
 
 ### Prerequisites
 
-- Go version 1.6 or higher.
-
-For installation instructions, see Go's [Getting Started](https://golang.org/doc/install) guide.
+- **Go** version 1.9+. For installation instructions, see Go's [Getting
+  Started](https://golang.org/doc/install) guide.
 
 #### gRPC
 
@@ -19,82 +18,77 @@ Use the following command to install gRPC.
 $ go get -u google.golang.org/grpc
 ```
 
-#### Protocol Buffers v3
-
-Install the protoc compiler that is used to generate gRPC service code. The simplest way to do this is to download pre-compiled binaries for your platform(`protoc-<version>-<platform>.zip`) from here: [https://github.com/google/protobuf/releases](https://github.com/google/protobuf/releases)
-
-  * Unzip this file.
-  * Update the environment variable `PATH` to include the path to the protoc binary file.
+#### Protocol Buffers
 
-Next, install the protoc plugin for Go
-
-```sh
-$ go get -u github.com/golang/protobuf/protoc-gen-go
-```
+While not mandatory, gRPC applications usually leverage [Protocol Buffers][pb]
+for service definitions and data serialization, and the example code uses
+[proto3][].
 
-The compiler plugin, `protoc-gen-go`, will be installed in `$GOBIN`, defaulting
-to `$GOPATH/bin`. It must be in your `PATH` for the protocol compiler, protoc,
-to find it.
+ 1. Install the `protoc` compiler:
 
-```sh
-$ export PATH=$PATH:$GOPATH/bin
-```
+    - macOS:
 
-### Download the example
+      ```sh
+      $ brew install protobuf
+      ```
 
-The grpc code that was fetched with `go get google.golang.org/grpc` also contains the examples. They can be found under the examples dir: `$GOPATH/src/google.golang.org/grpc/examples`.
+    - Any OS:
 
-### Build the example
+      1. Download a zip file of the latest version of pre-compiled binaries for
+          your operating system from [github.com/google/protobuf/releases][]
+          (`protoc-<version>-<os>.zip`).
+      2. Unzip the file.
+      3. Update your environment's path variable to include the path to the
+          `protoc` executable.
 
-Change to the example directory
+ 2. Install the `protoc` plugin for Go
 
-```sh
-$ cd $GOPATH/src/google.golang.org/grpc/examples/helloworld
-```
+    ```sh
+    $ go get -u github.com/golang/protobuf/protoc-gen-go
+    ```
 
-gRPC services are defined in a `.proto` file, which is used to generate a
-corresponding `.pb.go` file. The `.pb.go` file is generated by compiling the
-`.proto` file using the protocol compiler: `protoc`.
+ 3. Update your `PATH` so that the `protoc` compiler can find the plugin:
 
-For the purpose of this example, the `helloworld.pb.go` file has already been
-generated (by compiling `helloworld.proto`), and can be found in this directory:
-`$GOPATH/src/google.golang.org/grpc/examples/helloworld/helloworld`
+    ```sh
+    $ export PATH="$PATH:$(go env GOPATH)/bin"
+    ```
 
-This `helloworld.pb.go` file contains:
+### Run the example
 
-- Generated client and server code.
-- Code for populating, serializing, and retrieving our `HelloRequest` and
-  `HelloReply` message types.
+The grpc sources that you fetched in a previous step also contain the example
+code.
 
-### Try it!
+ 1. Change to the example's directory:
 
-To compile and run the server and client code, the `go run` command can be used.
-In the examples directory:
+    ```sh
+    $ cd $(go env GOPATH)/src/google.golang.org/grpc/examples/helloworld
+    ```
 
-```sh
-$ go run greeter_server/main.go
-```
+ 2. Compile and execute the server code:
 
-From a different terminal:
+    ```sh
+    $ go run greeter_server/main.go
+    ```
 
-```sh
-$ go run greeter_client/main.go
-```
+ 3. From a different terminal, compile and execute the client code to see the
+    client output:
 
-If things go smoothly, you will see the `Greeting: Hello world` in the client side output.
+    ```sh
+    $ go run greeter_client/main.go
+    Greeting: Hello world
+    ```
 
 Congratulations! You've just run a client-server application with gRPC.
 
 ### Update a gRPC service
 
-Now let's look at how to update the application with an extra method on the
-server for the client to call. Our gRPC service is defined using protocol
-buffers; you can find out lots more about how to define a service in a `.proto`
-file in [What is gRPC?](/docs/guides) and [gRPC Basics:
-Go](/docs/tutorials/basic/go/). For now all you need to know is that both the server and the client
-"stub" have a `SayHello` RPC method that takes a `HelloRequest` parameter from
-the client and returns a `HelloReply` from the server, and that this method
-is defined like this:
+In this section you'll update the application with an extra server method. The
+gRPC service is defined using [protocol buffers][pb]. To learn more about how to
+define a service in a `.proto` file see [gRPC Basics:
+Go](/docs/tutorials/basic/go). For now, all you need to know is that both the
+server and the client stub have a `SayHello()` RPC method that takes a
+`HelloRequest` parameter from the client and returns a `HelloReply` from the
+server, and that the method is defined like this:
 
 ```protobuf
 // The greeting service definition.
@@ -114,12 +108,8 @@ message HelloReply {
 }
 ```
 
-Let's update this so that the `Greeter` service has two methods. Make sure you
-are in the same examples dir as above
-(`$GOPATH/src/google.golang.org/grpc/examples/helloworld`).
-
-Edit `helloworld/helloworld.proto` and update it with a new `SayHelloAgain`
-method, with the same request and response types:
+Edit `helloworld/helloworld.proto` and add a new `SayHelloAgain()` method, with
+the same request and response types:
 
 ```protobuf
 // The greeting service definition.
@@ -141,26 +131,33 @@ message HelloReply {
 }
 ```
 
-### Generate gRPC code
+Remember to save the file!
 
-Next we need to update the gRPC code used by our application to use the new
-service definition. From the same examples dir as above
-(`$GOPATH/src/google.golang.org/grpc/examples/helloworld`):
+### Regenerate gRPC code
+
+Before you can use the new service method, you need to recompile the updated
+proto file.
+
+From the `examples/helloworld` directory, run the following command:
 
 ```sh
 $ protoc -I helloworld/ helloworld/helloworld.proto --go_out=plugins=grpc:helloworld
 ```
 
-This regenerates the helloworld.pb.go with our new changes.
+This will regenerate the `helloworld/helloworld.pb.go` file, which contains:
+
+- Code for populating, serializing, and retrieving `HelloRequest` and
+  `HelloReply` message types.
+- Generated client and server code.
 
 ### Update and run the application
 
-We now have new generated server and client code, but we still need to implement
-and call the new method in the human-written parts of our example application.
+You have regenerated server and client code, but you still need to implement
+and call the new method in the human-written parts of the example application.
 
 #### Update the server
 
-Edit `greeter_server/main.go` and add the following function to it:
+Open `greeter_server/main.go` and add the following function to it:
 
 ```go
 func (s *server) SayHelloAgain(ctx context.Context, in *pb.HelloRequest) (*pb.HelloReply, error) {
@@ -170,7 +167,8 @@ func (s *server) SayHelloAgain(ctx context.Context, in *pb.HelloRequest) (*pb.He
 
 #### Update the client
 
-Edit `greeter_client/main.go` to add the following code to the main function.
+Open `greeter_client/main.go` to add the following code to the end of the
+`main()` function body:
 
 ```go
 r, err = c.SayHelloAgain(ctx, &pb.HelloRequest{Name: name})
@@ -180,25 +178,31 @@ if err != nil {
 log.Printf("Greeting: %s", r.GetMessage())
 ```
 
+Remember to save your changes.
+
 #### Run!
 
+Run the client and server like you did before. Execute the following commands
+from the `examples/helloworld` directory:
+
  1. Run the server:
 
     ```sh
     $ go run greeter_server/main.go
     ```
 
- 2. On a different terminal, run the client:
+ 2. From another terminal, run the client. This time, add a name as a
+    command-line argument:
 
     ```sh
-    $ go run greeter_client/main.go
+    $ go run greeter_client/main.go Alice
     ```
 
     You'll see the following output:
 
     ```sh
-    Greeting: Hello world
-    Greeting: Hello again world
+    Greeting: Hello Alice
+    Greeting: Hello again Alice
     ```
 
 ### What's next
@@ -208,3 +212,7 @@ log.Printf("Greeting: %s", r.GetMessage())
 - Work through a more detailed tutorial in [gRPC Basics: Go](/docs/tutorials/basic/go/).
 - Explore the gRPC Go core API in its [reference
   documentation](https://godoc.org/google.golang.org/grpc).
+
+[github.com/google/protobuf/releases]: https://github.com/google/protobuf/releases
+[pb]: https://developers.google.com/protocol-buffers
+[proto3]: https://developers.google.com/protocol-buffers/docs/proto3