Merge pull request #4 from samstav/samstav-readme-updating-1

probably way too wordy

README.md

@@ -5,100 +5,42 @@ More info on the aws (s3/dynamo) backend supported by this module is found here:
 
 https://www.terraform.io/docs/backends/types/s3.html
 
-## Module options
-
-Options and configuration for this module are exposed via terraform variables.
-
-
-#### `backend_bucket`
-
-This is the only variable which has no default but is required. You will need to define this value in your terraform-aws-backend module block. There are a few ways to do this, here's a couple:
-
-```hcl
-module "backend" {
-  source = "github.com/samstav/terraform-aws-backend"
-  backend_bucket = "terraform-state-bucket"
-}
-```
-
-OR
-
-```hcl
-variable "backend_bucket" {
-  default = "terraform-state-bucket"
-}
-
-module "backend" {
-  source = "github.com/samstav/terraform-aws-backend"
-  backend_bucket = "${var.backend_bucket}"
-}
-```
-
-#### `dynamodb_lock_table_enabled`
-
-_Defaults to `true`._
-
-- Set to false or 0 to prevent this module from creating the DynamoDB table to use for terraform state locking and consistency. More info on locking for aws/s3 backends: https://www.terraform.io/docs/backends/types/s3.html. More information about how terraform handles booleans here: https://www.terraform.io/docs/configuration/variables.html"
-}
-
-#### `dynamodb_lock_table_stream_enabled`
-
-_Defaults to `false`._
-
-Affects terraform-aws-backend module behavior. Set to false or 0 to disable DynamoDB Streams for the table. More info on DynamoDB streams: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Streams.html. More information about how terraform handles booleans here: https://www.terraform.io/docs/configuration/variables.html
-
-
-#### `dynamodb_lock_table_stream_view_type`
-
-_Defaults to `NEW_AND_OLD_IMAGES`_
-
-Only applies if `dynamodb_lock_table_stream_enabled` is true.
-
-#### `dynamodb_lock_table_name`
-
-_Defaults to `terraform-lock`_
-
-The name of your [terraform state locking](https://www.terraform.io/docs/state/locking.html) DynamoDB Table.
-
-#### `lock_table_read_capacity`
-
-_Defaults to `1` Read Capacity Unit._
-
-More on DynamoDB Capacity Units: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/CapacityUnitCalculations.html
 
+# Bootstrapping your project
 
-#### `lock_table_write_capacity`
-_Defaults to `1` Write Capacity Unit._
+This terraform module helps you bootstrap any project which uses terraform for infrastructure management. [This module has a few options which are documented below. They allow you to change the behavior of this module.](#module-options)
 
-More on DynamoDB Capacity Units: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/CapacityUnitCalculations.html
+**_Why does this exist?_**
 
+One of the most popular backend options for terraform is AWS (S3 for state, and DynamoDB for the lock table). If your project [specifies an AWS/S3 backend](https://www.terraform.io/docs/backends/types/s3.html), Terraform requires the existence of an S3 bucket in which to store _state_ information about your project, and a DynamoDB table to use for locking (this prevents you, your collaborators, and CI from stepping on each other with terraform commands which either modify your state or the infrastructure itself).
 
-### terraform-aws-backend terraform variables
+This terraform module creates/manages those resources:
 
-See variables available for module configuration
+* Versioned S3 bucket for state
+* Properly configured DynamoDB lock table
 
-https://github.com/samstav/terraform-aws-backend/blob/master/variables.tf
+**If you follow this README carefully, you should be able to avoid the circular dependency which is inherent to the problem at hand.**
 
+**_What circular dependency?_**
 
-# Bootstrapping your project
+Your resulting terraform configuration block will refer to the resources created by this module. You wouldn't be able to `plan` or `apply` if your state bucket and lock table don't exist. The details which make this work can be seen under [the section which encourages you to postpone writing your terraform configuration block](#postpone-writing-your-terraform-configuration-block) and the [specific options used in the commands section below](#commands-are-the-fun-part).
 
 ### a note on state bucket and s3 key naming
 
 For the purposes of this intro, we'll use a bucket named `terraform-state-bucket`, but you'll want to choose an appropriate name for the s3 bucket in which terraform will store your infrastructure state. Perhaps something like `terraform-state-<your_project-name>`, or, if you store all of your terraform state for all projects in a single bucket, `bucket-with-all-of-my-tf-states` along with a `key` that defines a path/key name which is more project specific such as `states/project-x-terraform.tfstate`. 
 
 ### postpone writing your terraform configuration block
 
-In order to bootstrap your project with this module/setup, you will need to wait until **after** Step 4 (below) to write your [terraform configuration block](https://www.terraform.io/docs/configuration/terraform.html) into one of your `.tf` files. The one that looks like this `terraform {}`.
+In order to bootstrap your project with this module/setup, you will need to wait until **after** Step 4 (below) to write your [terraform configuration block](https://www.terraform.io/docs/configuration/terraform.html) into one of your `.tf` files. (Your "terraform configuration block" is the one that looks like this `terraform {}`.)
 
 
 ### describe your terraform backend resources
-
-The following code 
+
 ```hcl
 module "backend" {
   source = "github.com/samstav/terraform-aws-backend"
   backend_bucket = "terraform-state-bucket"
-  # if you dont want a dynamodb lock table, uncomment this:
+  # using options, e.g. if you dont want a dynamodb lock table, uncomment this:
   # dynamodb_lock_table_enabled = false
 }
 ```
@@ -152,3 +94,79 @@ terraform {
 Terraform might ask you if you want to copy your existing state. You probably do:
 
 ![yes](http://g.samstav.xyz/bgs7hwsiqa.png)
+
+## Module options
+
+Options and configuration for this module are exposed via terraform variables.
+
+
+#### `backend_bucket`
+
+This is the only variable which has no default but is required. You will need to define this value in your terraform-aws-backend module block. There are a few ways to do this, here's a couple:
+
+```hcl
+module "backend" {
+  source = "github.com/samstav/terraform-aws-backend"
+  backend_bucket = "terraform-state-bucket"
+}
+```
+
+OR
+
+```hcl
+variable "backend_bucket" {
+  default = "terraform-state-bucket"
+}
+
+module "backend" {
+  source = "github.com/samstav/terraform-aws-backend"
+  backend_bucket = "${var.backend_bucket}"
+}
+```
+
+#### `dynamodb_lock_table_enabled`
+
+_Defaults to `true`._
+
+- Set to false or 0 to prevent this module from creating the DynamoDB table to use for terraform state locking and consistency. More info on locking for aws/s3 backends: https://www.terraform.io/docs/backends/types/s3.html. More information about how terraform handles booleans here: https://www.terraform.io/docs/configuration/variables.html"
+}
+
+#### `dynamodb_lock_table_stream_enabled`
+
+_Defaults to `false`._
+
+Affects terraform-aws-backend module behavior. Set to false or 0 to disable DynamoDB Streams for the table. More info on DynamoDB streams: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Streams.html. More information about how terraform handles booleans here: https://www.terraform.io/docs/configuration/variables.html
+
+
+#### `dynamodb_lock_table_stream_view_type`
+
+_Defaults to `NEW_AND_OLD_IMAGES`_
+
+Only applies if `dynamodb_lock_table_stream_enabled` is true.
+
+#### `dynamodb_lock_table_name`
+
+_Defaults to `terraform-lock`_
+
+The name of your [terraform state locking](https://www.terraform.io/docs/state/locking.html) DynamoDB Table.
+
+#### `lock_table_read_capacity`
+
+_Defaults to `1` Read Capacity Unit._
+
+More on DynamoDB Capacity Units: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/CapacityUnitCalculations.html
+
+
+#### `lock_table_write_capacity`
+_Defaults to `1` Write Capacity Unit._
+
+More on DynamoDB Capacity Units: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/CapacityUnitCalculations.html
+
+
+### terraform-aws-backend terraform variables
+
+See variables available for module configuration
+
+https://github.com/samstav/terraform-aws-backend/blob/master/variables.tf
+
+