overhaul of top-level .md files

13 files changed, 724 insertions, 188 deletions

diff --git a/INSTALL.md b/BUILDING.md
index a61af3479c..e1d63a7461 100644
--- a/INSTALL.md
+++ b/BUILDING.md
@@ -1,18 +1,5 @@
-# If you are in a hurry
-
-For language-specific installation instructions for gRPC runtime, please
-refer to these documents
-
- * [C++](examples/cpp): Currently to install gRPC for C++, you need to build from source as described below.
- * [C#](src/csharp): NuGet package `Grpc`
- * [Go](https://github.com/grpc/grpc-go): `go get google.golang.org/grpc`
- * [Java](https://github.com/grpc/grpc-java)
- * [Node](src/node): `npm install grpc`
- * [Objective-C](src/objective-c)
- * [PHP](src/php): `pecl install grpc`
- * [Python](src/python/grpcio): `pip install grpcio`
- * [Ruby](src/ruby): `gem install grpc`
-
+gRPC C++ - Building from source
+===========================
 
 # Pre-requisites
 
@@ -28,7 +15,7 @@ If you plan to build from source and run tests, install the following as well:
  $ [sudo] apt-get install clang libc++-dev
 ```
 
-## macOS 
+## MacOS
 
 On a Mac, you will first need to
 install Xcode or
@@ -60,6 +47,17 @@ installed by `brew` is being used:
  $ LIBTOOL=glibtool LIBTOOLIZE=glibtoolize make
 ```
 
+## Windows
+
+To prepare for cmake + Microsoft Visual C++ compiler build
+- Install Visual Studio 2015 or 2017 (Visual C++ compiler will be used).
+- Install [Git](https://git-scm.com/).
+- Install [CMake](https://cmake.org/download/).
+- Install [Active State Perl](https://www.activestate.com/activeperl/) (`choco install activeperl`) - *required by boringssl*
+- Install [Go](https://golang.org/dl/) (`choco install golang`) - *required by boringssl*
+- Install [yasm](http://yasm.tortall.net/) and add it to `PATH` (`choco install yasm`) - *required by boringssl*
+- (Optional) Install [Ninja](https://ninja-build.org/) (`choco install ninja`)
+
 ## Protoc
 
 By default gRPC uses [protocol buffers](https://github.com/google/protobuf),
@@ -77,48 +75,49 @@ $ cd grpc/third_party/protobuf
 $ sudo make install   # 'make' should have been run by core grpc
 ```
 
-# Build from Source
+# Clone the repository (including submodules)
 
-For developers who are interested to contribute, the following commands show how to compile the
-gRPC C Core library.
+Before building, you need to clone the gRPC github repository and download submodules containing source code 
+for gRPC's dependencies (that's done by the `submodule` command or `--recursive` flag). The following commands will clone the gRPC
+repository at the latest stable version.
+
+## Unix
 
 ```sh
  $ git clone -b $(curl -L https://grpc.io/release) https://github.com/grpc/grpc
  $ cd grpc
  $ git submodule update --init
- $ make
- $ [sudo] make install
-```
+ ```
 
 ## Windows
 
-There are several ways to build under Windows, of varying complexity depending
-on experience with the tools involved.
+```
+> @rem You can also do just "git clone --recursive -b THE_BRANCH_YOU_WANT https://github.com/grpc/grpc"
+> powershell git clone --recursive -b ((New-Object System.Net.WebClient).DownloadString(\"https://grpc.io/release\").Trim()) https://github.com/grpc/grpc
+> cd grpc
+> @rem To update submodules at later time, run "git submodule update --init"
+```
 
+# Build from source
 
+In the C++ world, there's no "standard" build system that would work for in all supported use cases and on all supported platforms.
+Therefore, gRPC supports several major build systems, which should satisfy most users.
 
-### Building using CMake (RECOMMENDED)
+## make (on UNIX systems)
 
-Builds gRPC C and C++ with boringssl.
-- Install Visual Studio 2015 or 2017 (Visual C++ compiler will be used).
-- Install [Git](https://git-scm.com/).
-- Install [CMake](https://cmake.org/download/).
-- Install [Active State Perl](https://www.activestate.com/activeperl/) (`choco install activeperl`) - *required by boringssl*
-- Install [Go](https://golang.org/dl/) (`choco install golang`) - *required by boringssl*
-- Install [yasm](http://yasm.tortall.net/) and add it to `PATH` (`choco install yasm`) - *required by boringssl*
-- (Optional) Install [Ninja](https://ninja-build.org/) (`choco install ninja`)
+From the grpc repository root
+```sh
+ $ make
+```
 
-#### Clone grpc sources including submodules
-Before building, you need to clone the gRPC github repository and download submodules containing source code 
-for gRPC's dependencies (that's done by the `submodule` command).
+## bazel
+
+From the grpc repository root
 ```
-> @rem You can also do just "git clone --recursive -b THE_BRANCH_YOU_WANT https://github.com/grpc/grpc"
-> powershell git clone --recursive -b ((New-Object System.Net.WebClient).DownloadString(\"https://grpc.io/release\").Trim()) https://github.com/grpc/grpc
-> cd grpc
-> @rem To update submodules at later time, run "git submodule update --init"
+bazel build :all
 ```
 
-#### cmake: Using Visual Studio 2015 or 2017 (can only build with OPENSSL_NO_ASM).
+## cmake: Windows, Using Visual Studio 2015 or 2017 (can only build with OPENSSL_NO_ASM).
 When using the "Visual Studio" generator,
 cmake will generate a solution (`grpc.sln`) that contains a VS project for 
 every target defined in `CMakeLists.txt` (+ few extra convenience projects
@@ -132,7 +131,7 @@ you will be able to browse and build the code.
 > cmake --build .
 ```
 
-#### cmake: Using Ninja (faster build, supports boringssl's assembly optimizations).
+## cmake: Windows, Using Ninja (faster build, supports boringssl's assembly optimizations).
 Please note that when using Ninja, you will still need Visual C++ (part of Visual Studio)
 installed to be able to compile the C/C++ sources.
 ```
@@ -143,30 +142,3 @@ installed to be able to compile the C/C++ sources.
 > cmake .. -GNinja -DCMAKE_BUILD_TYPE=Release
 > cmake --build .
 ```
-
-### msys2 (with mingw)
-
-The Makefile (and source code) should support msys2's mingw32 and mingw64
-compilers. Building with msys2's native compiler is possible, but
-difficult.
-
-This approach requires having [msys2](https://msys2.github.io/) installed.
-
-```
-# Install prerequisites
-MSYS2$ pacman -S autoconf automake gcc libtool mingw-w64-x86_64-toolchain perl pkg-config zlib
-MSYS2$ pacman -S mingw-w64-x86_64-gflags
-```
-
-```
-# From mingw shell
-MINGW64$ export CPPFLAGS="-D_WIN32_WINNT=0x0600"
-MINGW64$ make
-```
-
-NOTE: Though most of the make targets are buildable under Mingw, some haven't been ported to Windows yet
-and may fail to build (mostly trying to include POSIX headers not available on Mingw).
-
-### Pre-generated Visual Studio solution (DELETED)
-
-*WARNING: This used to be the recommended way to build on Windows, but because of significant limitations (hard to build dependencies including boringssl, .proto codegen is hard to support, ..) we are no longer providing them. Use cmake to build on Windows instead.*
diff --git a/CONCEPTS.md b/CONCEPTS.md
new file mode 100644
index 0000000000..6855d43d39
--- /dev/null
+++ b/CONCEPTS.md
@@ -0,0 +1,62 @@
+# gRPC Concepts Overview
+
+Remote Procedure Calls (RPCs) provide a useful abstraction for building
+distributed applications and services. The libraries in this repository
+provide a concrete implementation of the gRPC protocol, layered over HTTP/2.
+These libraries enable communication between clients and servers using any
+combination of the supported languages.
+
+
+## Interface
+
+Developers using gRPC start with the description of an RPC service (a collection
+of methods), and generate client and server side interfaces. The server implements
+the service interface, which can be remotely invoked by the client interface.
+
+By default, gRPC uses [Protocol Buffers](https://github.com/google/protobuf) as the
+Interface Definition Language (IDL) for describing both the service interface
+and the structure of the payload messages. It is possible to use other
+alternatives if desired.
+
+### Invoking & handling remote calls
+Starting from an interface definition in a .proto file, gRPC provides
+Protocol Compiler plugins that generate Client- and Server-side APIs.
+gRPC users call into these APIs on the Client side and implement
+the corresponding API on the server side.
+
+#### Synchronous vs. asynchronous
+Synchronous RPC calls, that block until a response arrives from the server, are
+the closest approximation to the abstraction of a procedure call that RPC
+aspires to.
+
+On the other hand, networks are inherently asynchronous and in many scenarios,
+it is desirable to have the ability to start RPCs without blocking the current
+thread.
+
+The gRPC programming surface in most languages comes in both synchronous and
+asynchronous flavors.
+
+
+## Streaming
+
+gRPC supports streaming semantics, where either the client or the server (or both)
+send a stream of messages on a single RPC call. The most general case is
+Bidirectional Streaming where a single gRPC call establishes a stream where both
+the client and the server can send a stream of messages to each other. The streamed
+messages are delivered in the order they were sent.
+
+
+# Protocol
+
+The [gRPC protocol](doc/PROTOCOL-HTTP2.md) specifies the abstract requirements for communication between
+clients and servers. A concrete embedding over HTTP/2 completes the picture by
+fleshing out the details of each of the required operations.
+
+## Abstract gRPC protocol
+A gRPC call comprises of a bidirectional stream of messages, initiated by the client. In the client-to-server direction, this stream begins with a mandatory `Call Header`, followed by optional `Initial-Metadata`, followed by zero or more `Payload Messages`. The server-to-client direction contains an optional `Initial-Metadata`, followed by zero or more `Payload Messages` terminated with a mandatory `Status` and optional `Status-Metadata` (a.k.a.,`Trailing-Metadata`).
+
+## Implementation over HTTP/2
+The abstract protocol defined above is implemented over [HTTP/2](https://http2.github.io/). gRPC bidirectional streams are mapped to HTTP/2 streams. The contents of `Call Header` and `Initial Metadata` are sent as HTTP/2 headers and subject to HPACK compression. `Payload Messages` are serialized into a byte stream of length prefixed gRPC frames which are then fragmented into HTTP/2 frames at the sender and reassembled at the receiver. `Status` and `Trailing-Metadata` are sent as HTTP/2 trailing headers (a.k.a., trailers).
+
+## Flow Control
+gRPC uses the flow control mechanism in HTTP/2. This enables fine-grained control of memory used for buffering in-flight messages.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2f90ccf281..abd7a5eb78 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,13 +11,34 @@ In order to protect both you and ourselves, you will need to sign the
 [Contributor License
 Agreement](https://identity.linuxfoundation.org/projects/cncf).
 
-## Running tests
+## Cloning the repository
 
-Use `tools/run_tests/run_tests.py` script to run the unit tests.  See
-[tools/run_tests](tools/run_tests) for how to run tests for a given language.
+Before starting any development work you will need a local copy of the gRPC repository.
+Please follow the instructions in [Building gRPC C++: Clone the repository](BUILDING.md#clone-the-repository-including-submodules).
 
-Prerequisites for building and running tests are listed in
-[INSTALL.md](INSTALL.md) and in `src/YOUR-LANGUAGE` (e.g. `src/csharp`)
+## Building & Running tests
+
+Different languages use different build systems. To hide the complexity
+of needing to build with many different build systems, a portable python
+script that unifies the experience of building and testing gRPC in different
+languages and on different platforms is provided.
+
+To build gRPC in the language of choice (e.g. `c++`, `csharp`, `php`, `python`, `ruby`, ...)
+- Prepare you development environment based on language-specific instructions in `src/YOUR-LANGUAGE` directory.
+- The language-specific instructions might involve installing C/C++ prerequisites listed in
+  [Building gRPC C++: Prerequisites](BUILDING.md#pre-requisites) as gRPC implementations
+  in this repository are using the native gRPC "core" library internally.
+- Run
+  ```
+  python tools/run_tests/run_tests.py -l YOUR_LANGUAGE --build_only
+  ```
+- To also run all the unit tests after building
+  ```
+  python tools/run_tests/run_tests.py -l YOUR_LANGUAGE
+  ```
+
+You can also run `python tools/run_tests/run_tests.py --help` to discover useful command line flags supported. For more details,
+see [tools/run_tests](tools/run_tests) where you will also find guidance on how to run various other test suites (e.g. interop tests, benchmarks)
 
 ## Generated project files
 
diff --git a/README.md b/README.md
index 21a9910e3e..23964e7fc6 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,59 @@
-[gRPC - An RPC library and framework](http://github.com/grpc/grpc)
+gRPC - An RPC library and framework
 ===================================
 
+gRPC is a modern, open source, high-performance remote procedure call (RPC) framework that can run anywhere. It enables client and server applications to communicate transparently, and makes it easier to build connected systems.
+
+<table>
+  <tr>
+    <td><b>Homepage:</b></td>
+    <td><a href="https://grpc.io/">grpc.io</a></td>
+  </tr>
+  <tr>
+    <td><b>Mailing List:</b></td>
+    <td><a href="https://groups.google.com/forum/#!forum/grpc-io">grpc-io@googlegroups.com</a></td>
+  </tr>
+</table>
+
 [![Join the chat at https://gitter.im/grpc/grpc](https://badges.gitter.im/grpc/grpc.svg)](https://gitter.im/grpc/grpc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-Copyright 2015
-[The gRPC Authors](https://github.com/grpc/grpc/blob/master/AUTHORS)
+# To start using gRPC
+
+To maximize usability, gRPC supports the standard way of adding dependencies in your language of choice (if there is one).
+In most languages, the gRPC runtime comes in form of a package available in your language's package manager.
+
+For instructions on how to use the language-specific gRPC runtime in your project, please refer to these documents
 
-# Documentation
+ * [C++](src/cpp): follow the instructions under the `src/cpp` directory
+ * [C#](src/csharp): NuGet package `Grpc`
+ * [Dart](https://github.com/grpc/grpc-dart): pub package `grpc`
+ * [Go](https://github.com/grpc/grpc-go): `go get google.golang.org/grpc`
+ * [Java](https://github.com/grpc/grpc-java): Use JARs from Maven Central Repository
+ * [Node](https://github.com/grpc/grpc-node): `npm install grpc`
+ * [Objective-C](src/objective-c): Add `gRPC-ProtoRPC` dependency to podspec
+ * [PHP](src/php): `pecl install grpc`
+ * [Python](src/python/grpcio): `pip install grpcio`
+ * [Ruby](src/ruby): `gem install grpc`
+ * [WebJS](https://github.com/grpc/grpc-web): follow the grpc-web instructions
 
-You can find more detailed documentation and examples in the [doc](doc) and [examples](examples) directories respectively.
+You can find per-language quickstart guides and tutorials in [Documentation section on grpc.io website](https://grpc.io/docs/). The code examples are available in the [examples](examples) directory.
 
-# Installation & Testing
+# To start developing gRPC
 
-See [INSTALL](INSTALL.md) for installation instructions for various platforms.
+Contributions are welcome!
 
-See [tools/run_tests](tools/run_tests) for more guidance on how to run various test suites (e.g. unit tests, interop tests, benchmarks)
+Please read [How to contribute](CONTRIBUTING.md) which will guide you through the entire workflow of how to build the source code, how to run the tests and how to contribute your changes to
+the gRPC codebase.
+The document also contains info on how the contributing process works and contains best practices for creating contributions.
+
+# Performance 
 
 See [Performance dashboard](http://performance-dot-grpc-testing.appspot.com/explore?dashboard=5636470266134528) for the performance numbers for the latest released version.
 
-# Repository Structure & Status
+# Concepts
+
+See [gRPC Concepts](CONCEPTS.md)
+
+# About This Repository
 
 This repository contains source code for gRPC libraries for multiple languages written on top of shared C core library [src/core](src/core).
 
@@ -42,70 +77,3 @@ Libraries in different languages may be in different states of development. We a
 | WebJS                   | [grpc-web](https://github.com/grpc/grpc-web)         |
 | Dart                    | [grpc-dart](https://github.com/grpc/grpc-dart)       |
 
-See [MANIFEST.md](MANIFEST.md) for a listing of top-level items in the
-repository.
-
-# Overview
-
-
-Remote Procedure Calls (RPCs) provide a useful abstraction for building
-distributed applications and services. The libraries in this repository
-provide a concrete implementation of the gRPC protocol, layered over HTTP/2.
-These libraries enable communication between clients and servers using any
-combination of the supported languages.
-
-
-## Interface
-
-
-Developers using gRPC typically start with the description of an RPC service
-(a collection of methods), and generate client and server side interfaces
-which they use on the client-side and implement on the server side.
-
-By default, gRPC uses [Protocol Buffers](https://github.com/google/protobuf) as the
-Interface Definition Language (IDL) for describing both the service interface
-and the structure of the payload messages. It is possible to use other
-alternatives if desired.
-
-### Surface API
-Starting from an interface definition in a .proto file, gRPC provides
-Protocol Compiler plugins that generate Client- and Server-side APIs.
-gRPC users typically call into these APIs on the Client side and implement
-the corresponding API on the server side.
-
-#### Synchronous vs. asynchronous
-Synchronous RPC calls, that block until a response arrives from the server, are
-the closest approximation to the abstraction of a procedure call that RPC
-aspires to.
-
-On the other hand, networks are inherently asynchronous and in many scenarios,
-it is desirable to have the ability to start RPCs without blocking the current
-thread.
-
-The gRPC programming surface in most languages comes in both synchronous and
-asynchronous flavors.
-
-
-## Streaming
-
-gRPC supports streaming semantics, where either the client or the server (or both)
-send a stream of messages on a single RPC call. The most general case is
-Bidirectional Streaming where a single gRPC call establishes a stream where both
-the client and the server can send a stream of messages to each other. The streamed
-messages are delivered in the order they were sent.
-
-
-# Protocol
-
-The [gRPC protocol](doc/PROTOCOL-HTTP2.md) specifies the abstract requirements for communication between
-clients and servers. A concrete embedding over HTTP/2 completes the picture by
-fleshing out the details of each of the required operations.
-
-## Abstract gRPC protocol
-A gRPC RPC comprises of a bidirectional stream of messages, initiated by the client. In the client-to-server direction, this stream begins with a mandatory `Call Header`, followed by optional `Initial-Metadata`, followed by zero or more `Payload Messages`. The server-to-client direction contains an optional `Initial-Metadata`, followed by zero or more `Payload Messages` terminated with a mandatory `Status` and optional `Status-Metadata` (a.k.a.,`Trailing-Metadata`).
-
-## Implementation over HTTP/2
-The abstract protocol defined above is implemented over [HTTP/2](https://http2.github.io/). gRPC bidirectional streams are mapped to HTTP/2 streams. The contents of `Call Header` and `Initial Metadata` are sent as HTTP/2 headers and subject to HPACK compression. `Payload Messages` are serialized into a byte stream of length prefixed gRPC frames which are then fragmented into HTTP/2 frames at the sender and reassembled at the receiver. `Status` and `Trailing-Metadata` are sent as HTTP/2 trailing headers (a.k.a., trailers).
-
-## Flow Control
-gRPC inherits the flow control mechanisms in HTTP/2 and uses them to enable fine-grained control of the amount of memory used for buffering in-flight messages.
diff --git a/doc/command_line_tool.md b/doc/command_line_tool.md
index 082e6402eb..6337acaf60 100644
--- a/doc/command_line_tool.md
+++ b/doc/command_line_tool.md
@@ -32,7 +32,7 @@ The command line tool should support the following things:
 
 To use the tool, you need to get the grpc repository and make sure your system
 has the prerequisites for building grpc from source, given in the [installation
-instructions](https://github.com/grpc/grpc/blob/master/INSTALL.md).
+instructions](../BUILDING.md).
 
 In order to build the grpc command line tool from a fresh clone of the grpc
 repository, you need to run the following command to update submodules:
diff --git a/examples/cpp/README.md b/examples/cpp/README.md
index 8e2bb5d13b..0e358bf9a2 100644
--- a/examples/cpp/README.md
+++ b/examples/cpp/README.md
@@ -3,7 +3,7 @@
 ## Installation
 
 To install gRPC on your system, follow the instructions to build from source
-[here](../../INSTALL.md). This also installs the protocol buffer compiler
+[here](../../BUILDING.md). This also installs the protocol buffer compiler
 `protoc` (if you don't have it already), and the C++ gRPC plugin for `protoc`.
 
 ## Hello C++ gRPC!
diff --git a/examples/cpp/cpptutorial.md b/examples/cpp/cpptutorial.md
new file mode 100644
index 0000000000..c40676de13
--- /dev/null
+++ b/examples/cpp/cpptutorial.md
@@ -0,0 +1,488 @@
+# gRPC Basics: C++
+
+This tutorial provides a basic C++ programmer's introduction to working with
+gRPC. By walking through this example you'll learn how to:
+
+- Define a service in a `.proto` file.
+- Generate server and client code using the protocol buffer compiler.
+- Use the C++ gRPC API to write a simple client and server for your service.
+
+It assumes that you are familiar with
+[protocol buffers](https://developers.google.com/protocol-buffers/docs/overview).
+Note that the example in this tutorial uses the proto3 version of the protocol
+buffers language, which is currently in alpha release: you can find out more in
+the [proto3 language guide](https://developers.google.com/protocol-buffers/docs/proto3)
+and see the [release notes](https://github.com/google/protobuf/releases) for the
+new version in the protocol buffers Github repository.
+
+## Why use gRPC?
+
+Our example is a simple route mapping application that lets clients get
+information about features on their route, create a summary of their route, and
+exchange route information such as traffic updates with the server and other
+clients.
+
+With gRPC we can define our service once in a `.proto` file and implement clients
+and servers in any of gRPC's supported languages, which in turn can be run in
+environments ranging from servers inside Google to your own tablet - all the
+complexity of communication between different languages and environments is
+handled for you by gRPC. We also get all the advantages of working with protocol
+buffers, including efficient serialization, a simple IDL, and easy interface
+updating.
+
+## Example code and setup
+
+The example code for our tutorial is in [examples/cpp/route_guide](route_guide).
+You also should have the relevant tools installed to generate the server and
+client interface code - if you don't already, follow the setup instructions in
+[BUILDING.md](../../BUILDING.md).
+
+## Defining the service
+
+Our first step is to define the gRPC *service* and the method *request* and
+*response* types using
+[protocol buffers](https://developers.google.com/protocol-buffers/docs/overview).
+You can see the complete `.proto` file in
+[`examples/protos/route_guide.proto`](../protos/route_guide.proto).
+
+To define a service, you specify a named `service` in your `.proto` file:
+
+```protobuf
+service RouteGuide {
+   ...
+}
+```
+
+Then you define `rpc` methods inside your service definition, specifying their
+request and response types. gRPC lets you define four kinds of service method,
+all of which are used in the `RouteGuide` service:
+
+- A *simple RPC* where the client sends a request to the server using the stub
+  and waits for a response to come back, just like a normal function call.
+
+```protobuf
+   // Obtains the feature at a given position.
+   rpc GetFeature(Point) returns (Feature) {}
+```
+
+- A *server-side streaming RPC* where the client sends a request to the server
+  and gets a stream to read a sequence of messages back. The client reads from
+  the returned stream until there are no more messages. As you can see in our
+  example, you specify a server-side streaming method by placing the `stream`
+  keyword before the *response* type.
+
+```protobuf
+  // Obtains the Features available within the given Rectangle.  Results are
+  // streamed rather than returned at once (e.g. in a response message with a
+  // repeated field), as the rectangle may cover a large area and contain a
+  // huge number of features.
+  rpc ListFeatures(Rectangle) returns (stream Feature) {}
+```
+
+- A *client-side streaming RPC* where the client writes a sequence of messages
+  and sends them to the server, again using a provided stream. Once the client
+  has finished writing the messages, it waits for the server to read them all
+  and return its response. You specify a client-side streaming method by placing
+  the `stream` keyword before the *request* type.
+
+```protobuf
+  // Accepts a stream of Points on a route being traversed, returning a
+  // RouteSummary when traversal is completed.
+  rpc RecordRoute(stream Point) returns (RouteSummary) {}
+```
+
+- A *bidirectional streaming RPC* where both sides send a sequence of messages
+  using a read-write stream. The two streams operate independently, so clients
+  and servers can read and write in whatever order they like: for example, the
+  server could wait to receive all the client messages before writing its
+  responses, or it could alternately read a message then write a message, or
+  some other combination of reads and writes. The order of messages in each
+  stream is preserved. You specify this type of method by placing the `stream`
+  keyword before both the request and the response.
+
+```protobuf
+  // Accepts a stream of RouteNotes sent while a route is being traversed,
+  // while receiving other RouteNotes (e.g. from other users).
+  rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
+```
+
+Our `.proto` file also contains protocol buffer message type definitions for all
+the request and response types used in our service methods - for example, here's
+the `Point` message type:
+
+```protobuf
+// Points are represented as latitude-longitude pairs in the E7 representation
+// (degrees multiplied by 10**7 and rounded to the nearest integer).
+// Latitudes should be in the range +/- 90 degrees and longitude should be in
+// the range +/- 180 degrees (inclusive).
+message Point {
+  int32 latitude = 1;
+  int32 longitude = 2;
+}
+```
+
+## Generating client and server code
+
+Next we need to generate the gRPC client and server interfaces from our `.proto`
+service definition. We do this using the protocol buffer compiler `protoc` with
+a special gRPC C++ plugin.
+
+For simplicity, we've provided a [Makefile](route_guide/Makefile) that runs
+`protoc` for you with the appropriate plugin, input, and output (if you want to
+run this yourself, make sure you've installed protoc and followed the gRPC code
+[installation instructions](../../BUILDING.md) first):
+
+```shell
+$ make route_guide.grpc.pb.cc route_guide.pb.cc
+```
+
+which actually runs:
+
+```shell
+$ protoc -I ../../protos --grpc_out=. --plugin=protoc-gen-grpc=`which grpc_cpp_plugin` ../../protos/route_guide.proto
+$ protoc -I ../../protos --cpp_out=. ../../protos/route_guide.proto
+```
+
+Running this command generates the following files in your current directory:
+- `route_guide.pb.h`, the header which declares your generated message classes
+- `route_guide.pb.cc`, which contains the implementation of your message classes
+- `route_guide.grpc.pb.h`, the header which declares your generated service
+  classes
+- `route_guide.grpc.pb.cc`, which contains the implementation of your service
+  classes
+
+These contain:
+- All the protocol buffer code to populate, serialize, and retrieve our request
+  and response message types
+- A class called `RouteGuide` that contains
+   - a remote interface type (or *stub*) for clients to call with the methods
+     defined in the `RouteGuide` service.
+   - two abstract interfaces for servers to implement, also with the methods
+     defined in the `RouteGuide` service.
+
+
+<a name="server"></a>
+## Creating the server
+
+First let's look at how we create a `RouteGuide` server. If you're only
+interested in creating gRPC clients, you can skip this section and go straight
+to [Creating the client](#client) (though you might find it interesting
+anyway!).
+
+There are two parts to making our `RouteGuide` service do its job:
+- Implementing the service interface generated from our service definition:
+  doing the actual "work" of our service.
+- Running a gRPC server to listen for requests from clients and return the
+  service responses.
+
+You can find our example `RouteGuide` server in
+[route_guide/route_guide_server.cc](route_guide/route_guide_server.cc). Let's
+take a closer look at how it works.
+
+### Implementing RouteGuide
+
+As you can see, our server has a `RouteGuideImpl` class that implements the
+generated `RouteGuide::Service` interface:
+
+```cpp
+class RouteGuideImpl final : public RouteGuide::Service {
+...
+}
+```
+In this case we're implementing the *synchronous* version of `RouteGuide`, which
+provides our default gRPC server behaviour. It's also possible to implement an
+asynchronous interface, `RouteGuide::AsyncService`, which allows you to further
+customize your server's threading behaviour, though we won't look at this in
+this tutorial.
+
+`RouteGuideImpl` implements all our service methods. Let's look at the simplest
+type first, `GetFeature`, which just gets a `Point` from the client and returns
+the corresponding feature information from its database in a `Feature`.
+
+```cpp
+  Status GetFeature(ServerContext* context, const Point* point,
+                    Feature* feature) override {
+    feature->set_name(GetFeatureName(*point, feature_list_));
+    feature->mutable_location()->CopyFrom(*point);
+    return Status::OK;
+  }
+```
+
+The method is passed a context object for the RPC, the client's `Point` protocol
+buffer request, and a `Feature` protocol buffer to fill in with the response
+information. In the method we populate the `Feature` with the appropriate
+information, and then `return` with an `OK` status to tell gRPC that we've
+finished dealing with the RPC and that the `Feature` can be returned to the
+client.
+
+Now let's look at something a bit more complicated - a streaming RPC.
+`ListFeatures` is a server-side streaming RPC, so we need to send back multiple
+`Feature`s to our client.
+
+```cpp
+Status ListFeatures(ServerContext* context, const Rectangle* rectangle,
+                    ServerWriter<Feature>* writer) override {
+  auto lo = rectangle->lo();
+  auto hi = rectangle->hi();
+  long left = std::min(lo.longitude(), hi.longitude());
+  long right = std::max(lo.longitude(), hi.longitude());
+  long top = std::max(lo.latitude(), hi.latitude());
+  long bottom = std::min(lo.latitude(), hi.latitude());
+  for (const Feature& f : feature_list_) {
+    if (f.location().longitude() >= left &&
+        f.location().longitude() <= right &&
+        f.location().latitude() >= bottom &&
+        f.location().latitude() <= top) {
+      writer->Write(f);
+    }
+  }
+  return Status::OK;
+}
+```
+
+As you can see, instead of getting simple request and response objects in our
+method parameters, this time we get a request object (the `Rectangle` in which
+our client wants to find `Feature`s) and a special `ServerWriter` object. In the
+method, we populate as many `Feature` objects as we need to return, writing them
+to the `ServerWriter` using its `Write()` method. Finally, as in our simple RPC,
+we `return Status::OK` to tell gRPC that we've finished writing responses.
+
+If you look at the client-side streaming method `RecordRoute` you'll see it's
+quite similar, except this time we get a `ServerReader` instead of a request
+object and a single response. We use the `ServerReader`s `Read()` method to
+repeatedly read in our client's requests to a request object (in this case a
+`Point`) until there are no more messages: the server needs to check the return
+value of `Read()` after each call. If `true`, the stream is still good and it
+can continue reading; if `false` the message stream has ended.
+
+```cpp
+while (stream->Read(&point)) {
+  ...//process client input
+}
+```
+Finally, let's look at our bidirectional streaming RPC `RouteChat()`.
+
+```cpp
+  Status RouteChat(ServerContext* context,
+                   ServerReaderWriter<RouteNote, RouteNote>* stream) override {
+    std::vector<RouteNote> received_notes;
+    RouteNote note;
+    while (stream->Read(&note)) {
+      for (const RouteNote& n : received_notes) {
+        if (n.location().latitude() == note.location().latitude() &&
+            n.location().longitude() == note.location().longitude()) {
+          stream->Write(n);
+        }
+      }
+      received_notes.push_back(note);
+    }
+
+    return Status::OK;
+  }
+```
+
+This time we get a `ServerReaderWriter` that can be used to read *and* write
+messages. The syntax for reading and writing here is exactly the same as for our
+client-streaming and server-streaming methods. Although each side will always
+get the other's messages in the order they were written, both the client and
+server can read and write in any order — the streams operate completely
+independently.
+
+### Starting the server
+
+Once we've implemented all our methods, we also need to start up a gRPC server
+so that clients can actually use our service. The following snippet shows how we
+do this for our `RouteGuide` service:
+
+```cpp
+void RunServer(const std::string& db_path) {
+  std::string server_address("0.0.0.0:50051");
+  RouteGuideImpl service(db_path);
+
+  ServerBuilder builder;
+  builder.AddListeningPort(server_address, grpc::InsecureServerCredentials());
+  builder.RegisterService(&service);
+  std::unique_ptr<Server> server(builder.BuildAndStart());
+  std::cout << "Server listening on " << server_address << std::endl;
+  server->Wait();
+}
+```
+As you can see, we build and start our server using a `ServerBuilder`. To do this, we:
+
+1. Create an instance of our service implementation class `RouteGuideImpl`.
+1. Create an instance of the factory `ServerBuilder` class.
+1. Specify the address and port we want to use to listen for client requests
+   using the builder's `AddListeningPort()` method.
+1. Register our service implementation with the builder.
+1. Call `BuildAndStart()` on the builder to create and start an RPC server for
+   our service.
+1. Call `Wait()` on the server to do a blocking wait until process is killed or
+   `Shutdown()` is called.
+
+<a name="client"></a>
+## Creating the client
+
+In this section, we'll look at creating a C++ client for our `RouteGuide`
+service. You can see our complete example client code in
+[route_guide/route_guide_client.cc](route_guide/route_guide_client.cc).
+
+### Creating a stub
+
+To call service methods, we first need to create a *stub*.
+
+First we need to create a gRPC *channel* for our stub, specifying the server
+address and port we want to connect to without SSL:
+
+```cpp
+grpc::CreateChannel("localhost:50051", grpc::InsecureChannelCredentials());
+```
+
+Now we can use the channel to create our stub using the `NewStub` method
+provided in the `RouteGuide` class we generated from our `.proto`.
+
+```cpp
+public:
+ RouteGuideClient(std::shared_ptr<Channel> channel, const std::string& db)
+     : stub_(RouteGuide::NewStub(channel)) {
+   ...
+ }
+```
+
+### Calling service methods
+
+Now let's look at how we call our service methods. Note that in this tutorial
+we're calling the *blocking/synchronous* versions of each method: this means
+that the RPC call waits for the server to respond, and will either return a
+response or raise an exception.
+
+#### Simple RPC
+
+Calling the simple RPC `GetFeature` is nearly as straightforward as calling a
+local method.
+
+```cpp
+  Point point;
+  Feature feature;
+  point = MakePoint(409146138, -746188906);
+  GetOneFeature(point, &feature);
+
+...
+
+  bool GetOneFeature(const Point& point, Feature* feature) {
+    ClientContext context;
+    Status status = stub_->GetFeature(&context, point, feature);
+    ...
+  }
+```
+
+As you can see, we create and populate a request protocol buffer object (in our
+case `Point`), and create a response protocol buffer object for the server to
+fill in. We also create a `ClientContext` object for our call - you can
+optionally set RPC configuration values on this object, such as deadlines,
+though for now we'll use the default settings. Note that you cannot reuse this
+object between calls. Finally, we call the method on the stub, passing it the
+context, request, and response. If the method returns `OK`, then we can read the
+response information from the server from our response object.
+
+```cpp
+std::cout << "Found feature called " << feature->name()  << " at "
+          << feature->location().latitude()/kCoordFactor_ << ", "
+          << feature->location().longitude()/kCoordFactor_ << std::endl;
+```
+
+#### Streaming RPCs
+
+Now let's look at our streaming methods. If you've already read [Creating the
+server](#server) some of this may look very familiar - streaming RPCs are
+implemented in a similar way on both sides. Here's where we call the server-side
+streaming method `ListFeatures`, which returns a stream of geographical
+`Feature`s:
+
+```cpp
+std::unique_ptr<ClientReader<Feature> > reader(
+    stub_->ListFeatures(&context, rect));
+while (reader->Read(&feature)) {
+  std::cout << "Found feature called "
+            << feature.name() << " at "
+            << feature.location().latitude()/kCoordFactor_ << ", "
+            << feature.location().longitude()/kCoordFactor_ << std::endl;
+}
+Status status = reader->Finish();
+```
+
+Instead of passing the method a context, request, and response, we pass it a
+context and request and get a `ClientReader` object back. The client can use the
+`ClientReader` to read the server's responses. We use the `ClientReader`s
+`Read()` method to repeatedly read in the server's responses to a response
+protocol buffer object (in this case a `Feature`) until there are no more
+messages: the client needs to check the return value of `Read()` after each
+call. If `true`, the stream is still good and it can continue reading; if
+`false` the message stream has ended. Finally, we call `Finish()` on the stream
+to complete the call and get our RPC status.
+
+The client-side streaming method `RecordRoute` is similar, except there we pass
+the method a context and response object and get back a `ClientWriter`.
+
+```cpp
+    std::unique_ptr<ClientWriter<Point> > writer(
+        stub_->RecordRoute(&context, &stats));
+    for (int i = 0; i < kPoints; i++) {
+      const Feature& f = feature_list_[feature_distribution(generator)];
+      std::cout << "Visiting point "
+                << f.location().latitude()/kCoordFactor_ << ", "
+                << f.location().longitude()/kCoordFactor_ << std::endl;
+      if (!writer->Write(f.location())) {
+        // Broken stream.
+        break;
+      }
+      std::this_thread::sleep_for(std::chrono::milliseconds(
+          delay_distribution(generator)));
+    }
+    writer->WritesDone();
+    Status status = writer->Finish();
+    if (status.IsOk()) {
+      std::cout << "Finished trip with " << stats.point_count() << " points\n"
+                << "Passed " << stats.feature_count() << " features\n"
+                << "Travelled " << stats.distance() << " meters\n"
+                << "It took " << stats.elapsed_time() << " seconds"
+                << std::endl;
+    } else {
+      std::cout << "RecordRoute rpc failed." << std::endl;
+    }
+```
+
+Once we've finished writing our client's requests to the stream using `Write()`,
+we need to call `WritesDone()` on the stream to let gRPC know that we've
+finished writing, then `Finish()` to complete the call and get our RPC status.
+If the status is `OK`, our response object that we initially passed to
+`RecordRoute()` will be populated with the server's response.
+
+Finally, let's look at our bidirectional streaming RPC `RouteChat()`. In this
+case, we just pass a context to the method and get back a `ClientReaderWriter`,
+which we can use to both write and read messages.
+
+```cpp
+std::shared_ptr<ClientReaderWriter<RouteNote, RouteNote> > stream(
+    stub_->RouteChat(&context));
+```
+
+The syntax for reading and writing here is exactly the same as for our
+client-streaming and server-streaming methods. Although each side will always
+get the other's messages in the order they were written, both the client and
+server can read and write in any order — the streams operate completely
+independently.
+
+## Try it out!
+
+Build client and server:
+```shell
+$ make
+```
+Run the server, which will listen on port 50051:
+```shell
+$ ./route_guide_server
+```
+Run the client (in a different terminal):
+```shell
+$ ./route_guide_client
+```
diff --git a/examples/cpp/helloworld/README.md b/examples/cpp/helloworld/README.md
index 18d3d79dcc..c598658b1d 100644
--- a/examples/cpp/helloworld/README.md
+++ b/examples/cpp/helloworld/README.md
@@ -1,8 +1,8 @@
 # gRPC C++ Hello World Tutorial
 
 ### Install gRPC
-Make sure you have installed gRPC on your system. Follow the instructions here:
-[https://github.com/grpc/grpc/blob/master/INSTALL](../../../INSTALL.md).
+Make sure you have installed gRPC on your system. Follow the
+[BUILDING.md](../../../BUILDING.md) instructions.
 
 ### Get the tutorial source code
 
diff --git a/src/cpp/README.md b/src/cpp/README.md
index ac76bf74ed..f16cab1f44 100644
--- a/src/cpp/README.md
+++ b/src/cpp/README.md
@@ -1,13 +1,62 @@
 
 # Overview
 
-This directory contains source code for C++ implementation of gRPC.
+A C++ implementation of gRPC
 
-To install gRPC for C++ on your system, follow the instructions to build from source
-[here](../../INSTALL.md). This also installs the protocol buffer compiler
-`protoc` (if you don't have it already), and the C++ gRPC plugin for `protoc`.
+# To start using gRPC C++
 
-# Documentation
+In the C++ world, there's no universally accepted standard for managing project dependencies.
+Therefore, gRPC supports several major build systems, which should satisfy most users.
+
+## bazel
+
+We recommend using Bazel for projects that use gRPC as it will give you the best developer experience
+(easy handling of dependencies that support bazel & fast builds).
+
+To add gRPC as a dependency in bazel:
+1. determine commit SHA for the grpc release you want to use
+2. Use the [http_archive](https://docs.bazel.build/versions/master/be/workspace.html#http_archive) bazel rule to include gRPC source
+  ```
+  http_archive(
+      name = "grpc",
+      urls = [
+          "https://github.com/grpc/grpc/archive/YOUR_GRPC_COMMIT_SHA.tar.gz",
+      ],
+      strip_prefix = "grpc-YOUR_GRPC_COMMIT_SHA",
+  )
+  ```
+
+NOTE: currently bazel is only supported for building gRPC on Linux.
+
+## make
+
+Currently the default choice for building on UNIX based systems is `make`.
+
+To install gRPC for C++ on your system using `make`, follow the [Building gRPC C++](../../BUILDING.md)
+instructions to build from source and then install locally using `make install`.
+This also installs the protocol buffer compiler `protoc` (if you don't have it already),
+and the C++ gRPC plugin for `protoc`.
+
+WARNING: After installing with `make install` there is no easy way to uninstall, which can cause issues
+if you later want to remove the grpc and/or protobuf installation or upgrade to a newer version.
+
+## cmake
+
+`cmake` is the default build option on Windows, but also works on Linux, MacOS. `cmake` has good
+support for crosscompiling and can be used for targeting Android platform.
+
+If your project is using cmake, there are several ways to add gRPC dependency.
+- install gRPC via cmake first and then locate it with `find_package(gRPC CONFIG)`. [Example](../../examples/cpp/helloworld/CMakeLists.txt)
+- via cmake's `ExternalProject_Add` using a technique called "superbuild". [Example](../../examples/cpp/helloworld/cmake_externalproject/CMakeLists.txt)
+- add gRPC source tree to your project (preferrably as a git submodule) and add it to your cmake project with `add_subdirectory`. [Example](../../examples/cpp/helloworld/CMakeLists.txt)
+
+## Packaging systems
+
+There's no standard packaging system for C++. We've looked into supporting some (e.g. Conan and vcpkg) but we are not there yet.
+Contributions and community-maintained packages for popular packaging systems are welcome!
+
+
+## Examples & Additional Documentation
 
 You can find out how to build and run our simplest gRPC C++ example in our
 [C++ quick start](../../examples/cpp).
@@ -25,7 +74,6 @@ documentation site at [grpc.io](https://grpc.io), specifically:
   APIs.
 
 
-# Examples
+# To start developing gRPC C++
 
-Code examples for gRPC C++ live in this repository's
-[examples/cpp](../../examples/cpp) directory.
+For instructions on how to build gRPC C++ from source, follow the [Building gRPC C++](../../BUILDING.md) instructions.
diff --git a/src/csharp/README.md b/src/csharp/README.md
index e117e66afd..92be4bf1e5 100644
--- a/src/csharp/README.md
+++ b/src/csharp/README.md
@@ -42,7 +42,7 @@ If you are a user of gRPC C#, go to Usage section above.
 
 - [dotnet SDK](https://www.microsoft.com/net/core)
 - [Mono 4+](https://www.mono-project.com/) (only needed for Linux and MacOS)
-- Prerequisites mentioned in [INSTALL.md](../../INSTALL.md#pre-requisites)
+- Prerequisites mentioned in [BUILDING.md](../../BUILDING.md#pre-requisites)
   to be able to compile the native code.
 
 **Windows, Linux or Mac OS X**
@@ -93,6 +93,6 @@ THE NATIVE DEPENDENCY
 
 Internally, gRPC C# uses a native library written in C (gRPC C core) and invokes its functionality via P/Invoke. The fact that a native library is used should be fully transparent to the users and just installing the `Grpc.Core` NuGet package is the only step needed to use gRPC C# on all supported platforms.
 
-[API Reference]: https://grpc.io/grpc/csharp/
+[API Reference]: https://grpc.io/grpc/csharp/api/Grpc.Core.html
 [Helloworld Example]: ../../examples/csharp/helloworld
 [RouteGuide Tutorial]: https://grpc.io/docs/tutorials/basic/csharp.html 
diff --git a/tools/run_tests/python_utils/filter_pull_request_tests.py b/tools/run_tests/python_utils/filter_pull_request_tests.py
index 4c09b3414e..98a17fd1a7 100644
--- a/tools/run_tests/python_utils/filter_pull_request_tests.py
+++ b/tools/run_tests/python_utils/filter_pull_request_tests.py
@@ -96,7 +96,7 @@ _WHITELIST_DICT = {
     'gRPC\-Core\.podspec$': [_OBJC_TEST_SUITE],
     'gRPC\-ProtoRPC\.podspec$': [_OBJC_TEST_SUITE],
     'gRPC\-RxLibrary\.podspec$': [_OBJC_TEST_SUITE],
-    'INSTALL\.md$': [],
+    'BUILDING\.md$': [],
     'LICENSE$': [],
     'MANIFEST\.md$': [],
     'package\.json$': [_PHP_TEST_SUITE],
diff --git a/vsprojects/.gitignore b/vsprojects/.gitignore
deleted file mode 100644
index 8df1dcf0bf..0000000000
--- a/vsprojects/.gitignore
+++ /dev/null
@@ -1,12 +0,0 @@
-Debug
-Debug-DLL
-Release
-Release-DLL
-*.suo
-*.user
-test_bin
-*.opensdf
-*.sdf
-third_party/*.user
-/packages
-/IntDir
diff --git a/vsprojects/README.md b/vsprojects/README.md
deleted file mode 100644
index ee32ecab9a..0000000000
--- a/vsprojects/README.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Pre-generated MS Visual Studio project & solution files: DELETED
-
-**The pre-generated MS Visual Studio project & solution files are no longer available, please use cmake instead (it can generate Visual Studio projects for you).**
-
-**Pre-generated MS Visual Studio projects used to be the recommended way to build on Windows, but there were some limitations:**
-- **hard to build dependencies, expecially boringssl (deps usually support cmake quite well)**
-- **the nuget-based openssl & zlib dependencies are hard to maintain and update. We've received issues indicating that they are flawed.**
-- **.proto codegen is hard to support in Visual Studio directly (but we have a pretty decent support in cmake)**
-- **It's a LOT of generated files. We prefer not to have too much generated code in our github repo.**
-
-See [INSTALL.md](/INSTALL.md) for detailed instructions how to build using cmake on Windows.