documentation: explain provider dev environment setup

The intent here is just to introduce some initial docs on our recommended
way to develop plugins in the same GOPATH as Terraform itself. The
documentation in this area needs some more fundamental rework as it is
rather outdated and mis-organized, but that's outside the scope of what
this change is trying to achieve.

README.md

@@ -31,9 +31,10 @@ Developing Terraform
 
 If you wish to work on Terraform itself or any of its built-in providers, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.8+ is *required*). Alternatively, you can use the Vagrantfile in the root of this repo to stand up a virtual machine with the appropriate dev tooling already set up for you.
 
-Note that as of Terraform 0.10, most providers are no longer built in, and instead are located in their own repositories in the [terraform-providers](https://github.com/terraform-providers) organization on GitHub. Instructions for developing each provider are in the associated README file.
+This repository contains only Terraform core, which includes the command line interface and the main graph engine. Providers are implemented as plugins that each have their own repository in [the `terraform-providers` organization](https://github.com/terraform-providers) on GitHub. Instructions for developing each provider are in the associated README file. For more information, see [the provider development overview](https://www.terraform.io/docs/plugins/provider.html).
 
-For local dev first make sure Go is properly installed, including setting up a [GOPATH](http://golang.org/doc/code.html#GOPATH). You will also need to add `$GOPATH/bin` to your `$PATH`.
+For local development of Terraform core, first make sure Go is properly installed and that a
+[GOPATH](http://golang.org/doc/code.html#GOPATH) has been set. You will also need to add `$GOPATH/bin` to your `$PATH`.
 
 Next, using [Git](https://git-scm.com/), clone this repository into `$GOPATH/src/github.com/hashicorp/terraform`. All the necessary dependencies are either vendored or automatically installed, so you just need to type `make`. This will compile the code and then run the tests. If this exits with exit status 0, then everything is working!
 

website/docs/plugins/provider.html.md

@@ -32,6 +32,59 @@ of this page will assume you're familiar with
 [plugin basics](/docs/plugins/basics.html) and that you already have
 a basic development environment setup.
 
+## Provider Plugin Codebases
+
+Provider plugins live outside of the Terraform core codebase in their own
+source code repositories. The official set of provider plugins released by
+HashiCorp (developed by both HashiCorp staff and community contributors)
+all live in repositories in
+[the `terraform-providers` organization](https://github.com/terraform-providers)
+on GitHub, but third-party plugins can be maintained in any source code
+repository.
+
+When developing a provider plugin, it is recommended to use a common `GOPATH`
+that includes both the core Terraform repository and the repositories of any
+providers being changed. This makes it easier to use a locally-built
+`terraform` executable and a set of locally-built provider plugins together
+without further configuration.
+
+For example, to download both Terraform and the `template` provider into
+`GOPATH`:
+
+```
+$ go get github.com/hashicorp/terraform
+$ go get github.com/terraform-providers/terraform-provider-template
+```
+
+These two packages are both "main" packages that can be built into separate
+executables with `go install`:
+
+```
+$ go install github.com/hashicorp/terraform
+$ go install github.com/terraform-providers/terraform-provider-template
+```
+
+After running the above commands, both Terraform core and the `template`
+provider will both be installed in the current `GOPATH` and `$GOPATH/bin`
+will contain both `terraform` and `terraform-provider-template` executables.
+This `terraform` executable will find and use the `template` provider plugin
+alongside it in the `bin` directory in preference to downloading and installing
+an official release.
+
+When constructing a new provider from scratch, it's recommended to follow
+a similar repository structure as for the existing providers, with the main
+package in the repository root and a library package in a subdirectory named
+after the provider. For more information, see
+[the custom providers guide](/guides/writing-custom-terraform-providers.html).
+
+When making changes only to files within the provider repository, it is _not_
+necessary to re-build the main Terraform executable. Note that some packages
+from the Terraform repository are used as library dependencies by providers,
+such as `github.com/hashicorp/terraform/helper/schema`; it is recommended to
+use `govendor` to create a local vendor copy of the relevant packages in the
+provider repository, as can be seen in the repositories within the
+`terraform-providers` GitHub organization.
+
 ## Low-Level Interface
 
 The interface you must implement for providers is