Merge pull request #175 from mars/doc-improvements

Doc improvements

README.md

@@ -1,47 +1,35 @@
 [![Build Status](https://travis-ci.org/terraform-providers/terraform-provider-heroku.svg?branch=master)](https://travis-ci.org/terraform-providers/terraform-provider-heroku)
 
-Terraform Provider
-==================
+Terraform Provider Heroku
+=========================
 
-- Website: https://www.terraform.io
-- [![Gitter chat](https://badges.gitter.im/hashicorp-terraform/Lobby.png)](https://gitter.im/hashicorp-terraform/Lobby)
-- Mailing list: [Google Groups](http://groups.google.com/group/terraform-tool)
-- Documentation: https://www.terraform.io/docs/providers/heroku/index.html
+This provider is used to configure resources supported by the [Heroku Platform API](https://devcenter.heroku.com/articles/platform-api-reference).
+
+See the [official documentation](https://www.terraform.io/docs/providers/heroku/index.html) to use this provider in a Terraform configuration.
 
 <img src="https://cdn.rawgit.com/hashicorp/terraform-website/master/content/source/assets/images/logo-hashicorp.svg" width="600px">
 
 Requirements
 ------------
 
--	[Terraform](https://www.terraform.io/downloads.html) 0.10.x
--	[Go](https://golang.org/doc/install) 1.8 (to build the provider plugin)
+-	[Terraform](https://www.terraform.io/downloads.html) 0.11.x
+-	[Go](https://golang.org/doc/install) 1.11 (to build the provider plugin)
 
-Building The Provider
----------------------
+Development
+-----------
 
-Clone repository to: `$GOPATH/src/github.com/terraform-providers/terraform-provider-heroku`
+If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.11+ is *required*). You'll also need to correctly setup a [GOPATH](http://golang.org/doc/code.html#GOPATH), as well as adding `$GOPATH/bin` to your `$PATH`.
 
-```sh
-$ mkdir -p $GOPATH/src/github.com/terraform-providers; cd $GOPATH/src/github.com/terraform-providers
-$ git clone [email protected]:terraform-providers/terraform-provider-heroku
-```
+### Clone the Provider
 
-Enter the provider directory and build the provider
+With Go language, the repository must be cloned to a specific path in `$GOPATH/src` that matches its module import path.
 
 ```sh
-$ cd $GOPATH/src/github.com/terraform-providers/terraform-provider-heroku
-$ make build
+mkdir -p $GOPATH/src/github.com/terraform-providers
+cd $GOPATH/src/github.com/terraform-providers
+git clone [email protected]:terraform-providers/terraform-provider-heroku
 ```
 
-Using the provider
-----------------------
-## Fill in for each provider
-
-Developing the Provider
----------------------------
-
-If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.8+ is *required*). You'll also need to correctly setup a [GOPATH](http://golang.org/doc/code.html#GOPATH), as well as adding `$GOPATH/bin` to your `$PATH`.
-
 ### Build the Provider
 
 To compile the provider, run `make build`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
@@ -61,7 +49,7 @@ To use the dev provider with local Terraform, copy the freshly built plugin into
 cp $GOPATH/bin/terraform-provider-heroku ~/.terraform.d/plugins/
 ```
 
-Set the Heroku provider without a version constrain:
+Set the Heroku provider without a version constraint:
 
 ```hcl
 provider "heroku" {}

website/docs/index.html.markdown

@@ -3,16 +3,28 @@ layout: "heroku"
 page_title: "Provider: Heroku"
 sidebar_current: "docs-heroku-index"
 description: |-
-  The Heroku provider is used to interact with the resources supported by Heroku. The provider needs to be configured with the proper credentials before it can be used.
+  The Heroku provider is used to interact with the resources supported by the Heroku Platform API.
 ---
 
 # Heroku Provider
 
-The Heroku provider is used to interact with the resources supported by
-Heroku. The provider needs to be configured with the proper credentials
-before it can be used.
+This provider is used to interact with the resources supported by the Heroku Platform API. The provider needs to be configured with the proper credentials before it can be used.
 
-Use the navigation to the left to read about the available resources.
+## Background
+
+[Heroku](https://www.heroku.com)'s fully-managed platform gives you the simplest path to delivering apps quickly:
+
+  * [Using Terraform with Heroku](https://devcenter.heroku.com/articles/using-terraform-with-heroku)
+  * [Platform API reference](https://devcenter.heroku.com/articles/platform-api-reference)
+  * [Command Line Interface (CLI)](https://devcenter.heroku.com/articles/heroku-cli)
+
+## Contributing
+
+Development happens in the [GitHub repo](https://github.com/terraform-providers/terraform-provider-heroku):
+
+  * [Releases](https://github.com/terraform-providers/terraform-provider-heroku/releases)
+  * [Changelog](https://github.com/terraform-providers/terraform-provider-heroku/blob/master/CHANGELOG.md)
+  * [Issues](https://github.com/terraform-providers/terraform-provider-heroku/issues)
 
 ## Example Usage
 

website/docs/r/account_feature.html.markdown

@@ -3,23 +3,32 @@ layout: "heroku"
 page_title: "Heroku: heroku_account_feature"
 sidebar_current: "docs-heroku-resource-account-feature"
 description: |-
-  Provides a Heroku Account Feature resource.
+  Provides a resource to create and manage User Features on Heroku.
 ---
 
-# heroku\_account_feature
+# heroku\_account\_feature
 
-Provides a Heroku Account Feature resource. An account feature represents a Heroku labs capability
-that can be enabled or disabled for an account on Heroku.
+This resource is used to create and manage [User Features](https://devcenter.heroku.com/articles/heroku-beta-features) on Heroku.
 
 ~> **NOTE:** If this resource's HCL is removed from a `.tf` file, the behavior is to disable account feature
 and remove resource from state.
 
+## Available Features
+
+For a list of available features, use the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) to fetch them for the current user:
+
+```
+heroku labs
+```
+
+The output will contain **User Features** that may be managed with this resource.
+
 ## Example Usage
 
 ```hcl
 # Create a new Heroku app
-resource "heroku_account_feature" "foobar" {
-  name = "foobar"
+resource "heroku_account_feature" "example_metrics" {
+  name = "metrics-request-volume"
   enabled = true
 }
 ```
@@ -41,10 +50,10 @@ The following attributes are exported:
 
 ## Import
 
-Existing account feature can be imported using a combination of the account email (the email address tied to the Heroku API key)
-and the feature name
+Existing account features can be imported using a combination of the account email (the email address tied to the Heroku API key)
+and the feature name.
 
 For example:
 ```
-$ terraform import heroku_account_formation.foobar email@email.com:foobar-feature
+$ terraform import heroku_account_feature.example_metrics name@example.com:metrics-request-volume
 ```

website/docs/r/app_feature.html.markdown

@@ -3,12 +3,22 @@ layout: "heroku"
 page_title: "Heroku: heroku_app_feature"
 sidebar_current: "docs-heroku-resource-app-feature"
 description: |-
-  Provides a Heroku App Feature resource. This can be used to create and manage App Features on Heroku.
+  Provides a resource to create and manage App Features on Heroku.
 ---
 
 # heroku\_app\_feature
 
-Provides a Heroku App Feature resource. This can be used to create and manage App Features on Heroku.
+This resource is used to create and manage [App Features](https://devcenter.heroku.com/articles/heroku-beta-features) on Heroku.
+
+## Available Features
+
+For a list of available features, use the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) to fetch them for one of your existing apps:
+
+```
+heroku labs --app foobar
+```
+
+The output will contain **User Features** and **App Features**. This resource manages App Features. If you need to manage User Features, use the [`heroku_account_feature` resource](account_feature.html).
 
 ## Example Usage
 

website/docs/r/space_app_access.markdown

@@ -3,34 +3,34 @@ layout: "heroku"
 page_title: "Heroku: heroku_space_app_access"
 sidebar_current: "docs-heroku-resource-space-app-access"
 description: |-
-  Provides a Heroku Space resource for managing app permissions for the entire space. Members with the admin role will always have full permissions to a Heroku space, so using this resource on an admin will have no affect. The provided member must already exist in your Heroku organization.
+  Provides a Heroku Space App Access resource for managing permissions within the Private Space.
 ---
 
-# heroku\_space\_member
+# heroku\_space\_app\_access
 
-Provides a Heroku Space resource for managing app permissions for the entire space. Members with the admin role will always have full permissions to a Heroku Space, so using this resource on an admin will have no affect. The provided member must already exist in your Heroku organization. Currently the only supported permission is `create_apps`.
+Provides a resource for managing permissions for the entire Private Space. Members with the admin role will always have full permissions in the Private Space, so using this resource on an admin will have no effect. The provided email must already be a member of the Heroku Team. Currently the only supported permission is `create_apps`.
 
 ## Example Usage
 
 ```hcl
-// Create a new Heroku space
+// Create a new Heroku Private Space
 resource "heroku_space" "default" {
   name = "test-space"
   organization = "my-company"
   region = "virginia"
 }
 
-// Give an existing team member create_apps permissions to the space
+// Give an existing team member create_apps permissions to the Private Space
 resource "heroku_space_app_access" "member1" {
   space = "${heroku_space.default.name}"
-  email = "member1@foobar.com"
+  email = "member1@example.com"
   permissions = ["create_apps"]
 }
 
 // Remove all permissions from an existing team member
-resource "heroku_space_app_access" "member1" {
+resource "heroku_space_app_access" "member2" {
   space = "${heroku_space.default.name}"
-  email = "member1@foobar.com"
+  email = "member2@example.com"
   permissions = []
 }
 ```
@@ -39,13 +39,13 @@ resource "heroku_space_app_access" "member1" {
 
 The following arguments are supported:
 
-* `space` - (Required) The name of the space.
-* `email` - (Required) The email of the team member to set permissions for.
-* `permissions` - (Required) The permissions to grant the team member for the space. Currently `create_apps` is the only supported permission. If not provided the member will have no permissions to the space. Members with admin role will always have `create_apps` permissions, which cannot be removed.
+* `space` - (Required) The name of the Private Space.
+* `email` - (Required) The email of the existing Heroku Team member.
+* `permissions` - (Required) The permissions to grant the team member for the Private Space. Currently `create_apps` is the only supported permission. If not provided the member will have no permissions to the space. Members with admin role will always have `create_apps` permissions, which cannot be removed.
 
 ## Importing
 
-Existing slugs can be imported using the combination of the space name, a colon, and the member email.
+Existing permissions can be imported using the combination of the Private Space name, a colon, and the member email.
 
 For example: