diff --git a/README.md b/README.md
index c48007a1cbd..c123ba0a5a5 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,17 @@ platform-neutral remote procedure call (RPC) system developed at Google.
 This document introduces you to gRPC with a quick overview and a simple
 Hello World example. More documentation is coming soon!
 
+## What's in this repository?
+
+The `grpc-common` repository contains documentation, resources, and examples
+for all gRPC users. You can find examples and instructions specific to your
+favourite language in the relevant subdirectory.
+
+You can find out about the gRPC source code repositories in
+[`grpc`](https://github.com/grpc/grpc). Each repository provides instructions
+for building the appropriate libraries for your language.
+
+
 ## What is gRPC?
 
 In gRPC a *client* application can directly call
@@ -45,7 +56,11 @@ While protocol buffers have been available for open source users for some
 time, our examples use a new flavour of protocol buffers called proto3,
 which has a slightly simplified syntax, some useful new features, and supports
 lots more languages. This is currently available as an alpha release in
-[languages] from [wherever it's going], with more languages in development.
+Java, C++ from [the protocol buffers Github
+repo](https://github.com/google/protobuf/releases), as well as a Go language
+generator [wherever that is](), with more languages in development. Full
+documentation for proto3 is currently in development but you can see
+the major differences from the current default version in the [release notes](https://github.com/google/protobuf/releases).
 
 In general, we recommend that you use proto3 with gRPC as it lets you use the
 full range of gRPC-supported languages, as well as avoiding compatibility
@@ -69,23 +84,21 @@ a single
 Hello World method.
 - Create a Java server that implements this interface.
 - Create a Java client that accesses the Java server.
-- Create a [probably need a different language now] client that accesses
+- Create a Go client that accesses
 the same Java server.
-- Update the service with more advanced features like RPC streaming.
+- Update the service with a streaming RPC.
 
 The complete code for the example is available in the `grpc-common` GitHub
-repository. You can
-work along with the example and hack on the code in the comfort of your own
-computer, giving you hands-on practice of really writing
-gRPC code. We use the Git versioning system for source code management:
+repository. We use the Git versioning system for source code management:
 however, you don't need to know anything about Git to follow along other
 than how to install and run a few git commands.
 
 This is an introductory example rather than a comprehensive tutorial, so
 don't worry if you're not a Go or
-Java developer - the concepts introduced here are similar for all languages,
-and complete tutorials and reference documentation for all gRPC
-languages are coming soon.
+Java developer - the concepts are similar for all languages, and you can
+find more implementations of our Hello World example in other languages in
+the language-specific folders in this repository. Complete tutorials and
+reference documentation for all gRPC languages are coming soon.
 
 <a name="setup"></a>
 ### Setup
@@ -170,7 +183,7 @@ types as protocol buffer message types. Both the client and the
 server use interface code generated from the service definition.
 
 Here's our example service definition, defined using protocol buffers IDL in
-[helloworld.proto](java/src/main/proto/helloworld.proto). The `Greeting`
+[helloworld.proto](protos/helloworld.proto). The `Greeting`
 service has one method, `hello`, that lets the server receive a single
 `HelloRequest`
 message from the remote client containing the user's name, then send back
@@ -223,13 +236,8 @@ classes. By default `protoc` just generates code for reading and writing
 protocol buffers, so you need to use plugins to add additional features
 to generated code. As we're creating Java code, we use the gRPC Java plugin.
 
-To build the plugin:
-
-```sh
-$ pushd external/grpc_java
-$ make java_plugin
-$ popd
-```
+To build the plugin, follow the instructions in the relevant repo: for Java,
+the instructions are in [`grpc-java`](https://github.com/grpc/grpc-java).
 
 To use it to generate the code:
 
@@ -241,6 +249,8 @@ $ protoc -I . helloworld.proto
                                --java_out=src/main/java
 ```
 
+[need to update this once I get the plugin built]
+
 This generates the following classes, which contain all the generated code
 we need to create our example:
 
@@ -442,9 +452,58 @@ $ ./run_greeter_client.sh
 
 ### Adding another client
 
-
 Finally, let's look at one of gRPC's most useful features - interoperability
-between code in different languages. So far, we've just generated Java code
-from our `Greeter` service definition....
+between code in different languages. So far, we've just looked at Java code
+generated from and implementing our `Greeter` service definition. However,
+as you'll see if you look at the language-specific subdirectories
+in this repository, we've also generated and implemented `Greeter`
+in some of gRPC's other supported languages. Each service
+and client uses interface code generated from [exactly the same
+.proto](https://github.com/grpc/grpc-common/blob/master/protos/helloworld.proto)
+that we used for the Java example.
+
+So, for example, if we visit the [`go`
+directory](https://github.com/grpc/grpc-common/tree/master/go) and look at the
+[`greeter_client`](https://github.com/grpc/grpc-common/blob/master/go/greeter_client/main.go),
+we can see that like the Java client, it connects to a `Greeter` service
+at `localhost:50051` and uses a stub to call the `SayHello` method with a
+`HelloRequest`:
+
+```go
+const (
+	address = "localhost:50051"
+	defaultName = "world"
+)
+
+func main() {
+	// Set up a connection to the server.
+	conn, err := grpc.Dial(address)
+	if err != nil {
+		log.Fatalf("did not connect: %v", err)
+	}
+	defer conn.Close()
+	c := pb.NewGreeterClient(conn)
+
+	// Contact the server and print out its response.
+	name := defaultName
+	if len(os.Args) > 1 {
+		name = os.Args[1]
+	}
+	r, err := c.SayHello(context.Background(), &pb.HelloRequest{Name:
+	name})
+	if err != nil {
+		log.Fatalf("could not greet: %v", err)
+	}
+	log.Printf("Greeting: %s", r.Message)
+}
+```
+
+
+If we run the Java server from earlier in another terminal window, we can
+run the Go client and connect to it just like the Java client, even though
+it's written in a different language.
+
+```
+$ greeter_client
+```
 
-###TODO: Section on Go client for same server