README.md: Reorganize and trim

Reorganize the README to flow better for new users, pointing them in
good directions. Also try to reduce the size so they actually read the
thing. It's still to long, but is a step in the right direction.

Fixes #4615

1 files changed, 42 insertions, 83 deletions

diff --git a/README.md b/README.md
index 882bd19ce..7722ada21 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,17 @@ Provider on Android. Please see the [Security Readme](SECURITY.md).
 [![Build Status](https://travis-ci.org/grpc/grpc-java.svg?branch=master)](https://travis-ci.org/grpc/grpc-java)
 [![Coverage Status](https://coveralls.io/repos/grpc/grpc-java/badge.svg?branch=master&service=github)](https://coveralls.io/github/grpc/grpc-java?branch=master)
 
+Getting Started
+---------------
+
+For a guided tour, take a look at the [quick start
+guide](https://grpc.io/docs/quickstart/java.html) or the more explanatory [gRPC
+basics](https://grpc.io/docs/tutorials/basic/java.html).
+
+The [examples](https://github.com/grpc/grpc-java/tree/v1.14.0/examples) and the
+[Android example](https://github.com/grpc/grpc-java/tree/v1.14.0/examples/android)
+are standalone projects that showcase the usage of gRPC.
+
 Download
 --------
 
@@ -53,7 +64,7 @@ compile 'io.grpc:grpc-stub:1.14.0'
 ```
 
 For Android client, use `grpc-okhttp` instead of `grpc-netty-shaded` and
-`grpc-protobuf-lite` or `grpc-protobuf-nano` instead of `grpc-protobuf`:
+`grpc-protobuf-lite` instead of `grpc-protobuf`:
 ```gradle
 compile 'io.grpc:grpc-okhttp:1.14.0'
 compile 'io.grpc:grpc-protobuf-lite:1.14.0'
@@ -66,6 +77,9 @@ http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.grpc%22%20AND%20v%3A%221.14
 Development snapshots are available in [Sonatypes's snapshot
 repository](https://oss.sonatype.org/content/repositories/snapshots/).
 
+Generated Code
+--------------
+
 For protobuf-based codegen, you can put your proto files in the `src/main/proto`
 and `src/test/proto` directories along with an appropriate plugin.
 
@@ -110,7 +124,6 @@ For protobuf-based codegen integrated with the Maven build system, you can use
 For protobuf-based codegen integrated with the Gradle build system, you can use
 [protobuf-gradle-plugin][]:
 ```gradle
-apply plugin: 'java'
 apply plugin: 'com.google.protobuf'
 
 buildscript {
@@ -118,8 +131,6 @@ buildscript {
     mavenCentral()
   }
   dependencies {
-    // ASSUMES GRADLE 2.12 OR HIGHER. Use plugin version 0.7.5 with earlier
-    // gradle versions
     classpath 'com.google.protobuf:protobuf-gradle-plugin:0.8.5'
   }
 }
@@ -143,18 +154,32 @@ protobuf {
 
 [protobuf-gradle-plugin]: https://github.com/google/protobuf-gradle-plugin
 
+API Stability
+-------------
+
+APIs annotated with `@Internal` are for internal use by the gRPC library and
+should not be used by gRPC users. APIs annotated with `@ExperimentalApi` are
+subject to change in future releases, and library code that other projects
+may depend on should not use these APIs.
+
+We recommend using the
+[grpc-java-api-checker](https://github.com/grpc/grpc-java-api-checker)
+(an [Error Prone](https://github.com/google/error-prone) plugin)
+to check for usages of `@ExperimentalApi` and `@Internal` in any library code
+that depends on gRPC. It may also be used to check for `@Internal` usage or 
+unintended `@ExperimentalApi` consumption in non-library code.
+
 How to Build
 ------------
 
 If you are making changes to gRPC-Java, see the [compiling
 instructions](COMPILING.md).
 
-Navigating Around the Source
-----------------------------
+High-level Components
+---------------------
 
-Here's a quick readers' guide to the code to help folks get started. At a high
-level there are three distinct layers to the library: __Stub__, __Channel__ &
-__Transport__.
+At a high level there are three distinct layers to the library: *Stub*,
+*Channel*, and *Transport*.
 
 ### Stub
 
@@ -162,94 +187,28 @@ The Stub layer is what is exposed to most developers and provides type-safe
 bindings to whatever datamodel/IDL/interface you are adapting. gRPC comes with
 a [plugin](https://github.com/google/grpc-java/blob/master/compiler) to the
 protocol-buffers compiler that generates Stub interfaces out of `.proto` files,
-but bindings to other datamodel/IDL should be trivial to add and are welcome.
-
-#### Key Interfaces
-
-[Stream Observer](https://github.com/google/grpc-java/blob/master/stub/src/main/java/io/grpc/stub/StreamObserver.java)
+but bindings to other datamodel/IDL are easy and encouraged.
 
 ### Channel
 
 The Channel layer is an abstraction over Transport handling that is suitable for
 interception/decoration and exposes more behavior to the application than the
 Stub layer. It is intended to be easy for application frameworks to use this
-layer to address cross-cutting concerns such as logging, monitoring, auth etc.
-Flow-control is also exposed at this layer to allow more sophisticated
-applications to interact with it directly.
-
-#### Common
-
-* [Metadata - headers & trailers](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/Metadata.java)
-* [Status - error code namespace & handling](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/Status.java)
-
-#### Client
-* [Channel - client side binding](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/Channel.java)
-* [Client Call](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/ClientCall.java)
-* [Client Interceptor](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/ClientInterceptor.java)
-
-#### Server
-* [Server call handler - analog to Channel on server](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/ServerCallHandler.java)
-* [Server Call](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/ServerCall.java)
-
+layer to address cross-cutting concerns such as logging, monitoring, auth, etc.
 
 ### Transport
 
 The Transport layer does the heavy lifting of putting and taking bytes off the
 wire. The interfaces to it are abstract just enough to allow plugging in of
-different implementations. Transports are modeled as `Stream` factories. The
-variation in interface between a server Stream and a client Stream exists to
-codify their differing semantics for cancellation and error reporting.
-
-Note the transport layer API is considered internal to gRPC and has weaker API
-guarantees than the core API under package `io.grpc`.
+different implementations. Note the transport layer API is considered internal
+to gRPC and has weaker API guarantees than the core API under package `io.grpc`.
 
 gRPC comes with three Transport implementations:
 
-1. The [Netty-based](https://github.com/google/grpc-java/blob/master/netty)
-   transport is the main transport implementation based on
+1. The Netty-based transport is the main transport implementation based on
    [Netty](http://netty.io). It is for both the client and the server.
-2. The [OkHttp-based](https://github.com/google/grpc-java/blob/master/okhttp)
-   transport is a lightweight transport based on
+2. The OkHttp-based transport is a lightweight transport based on
    [OkHttp](http://square.github.io/okhttp/). It is mainly for use on Android
    and is for client only.
-3. The
-   [inProcess](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/inprocess)
-   transport is for when a server is in the same process as the client. It is
-   useful for testing.
-
-#### Common
-
-* [Stream](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/internal/Stream.java)
-* [Stream Listener](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/internal/StreamListener.java)
-
-#### Client
-
-* [Client Stream](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/internal/ClientStream.java)
-* [Client Stream Listener](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/internal/ClientStreamListener.java)
-
-#### Server
-
-* [Server Stream](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/internal/ServerStream.java)
-* [Server Stream Listener](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/internal/ServerStreamListener.java)
-
-
-Examples
---------
-
-The [examples](https://github.com/grpc/grpc-java/tree/master/examples)
-and the
-[Android example](https://github.com/grpc/grpc-java/tree/master/examples/android) are standalone projects that
-showcase the usage of gRPC.
-
-Tools
------
-
-APIs annotated with `@Internal` are for internal use by the gRPC library and
-should not be used by gRPC users. APIs annotated with `@ExperimentalApi` are
-subject to change in future releases, and library code that other projects
-may depend on should not use these APIs. We recommend using the
-[grpc-java-api-checker](https://github.com/grpc/grpc-java-api-checker)
-(an [Error Prone](https://github.com/google/error-prone) plugin)
-to check for usages of `@ExperimentalApi` and `@Internal` in any library code
-that depends on gRPC. It may also be used to check for `@Internal` usage or 
-unintended `@ExperimentalApi` consumption in non-library code.
+3. The in-process transport is for when a server is in the same process as the
+   client. It is useful for testing, while also being safe for production use.