Update various docs ahead of 1.x release. (#165)

docs/1.x-upgrade.md

@@ -116,6 +116,17 @@ reason to commit it to source control. Multiple developers can make
 changes to production environments with confidence knowning that only
 the changes they want to make are the changes that will be made.
 
+In interactive environments (and when `--no-interactive` is not
+passed), the `create` and `update` commands will ask the user for any
+missing parameters. In addition, `create` will ask the user if they
+want to use default values for parameters. In future versions, we'll
+add support for more of the native CloudFormation properties that
+define input validation, etc.
+
+The system which prompts users for information is pluggable on a
+per-parameter basis, allowing you to write custom plugins to get input
+configuration from third-party sources.
+
 ## AWS_CREDENTIAL_FILE support removed ##
 
 This legacy form of credential management hasn't been supported by the

docs/example.md

@@ -1,7 +1,8 @@
 # Example usage of the Moonshot Library
 
-In this example we are going to use the resources in the sample directory.
-This example assumes you have access to an Amazon AWS account and have sufficient permissions to create roles and resources.
+In this example we are going to use the resources in the sample
+directory.  This example assumes you have access to an Amazon AWS
+account and have sufficient permissions to create roles and resources.
 
 ## So, what's in it for me?
 
@@ -70,16 +71,6 @@ $ aws s3api create-bucket --bucket moonshot-sample-your-name
 
 Then update `Moonfile.rb` to refer to that bucket in the `S3Bucket` configuration.
 
-### Create a configuration for your stack.
-
-We'll have to copy the base stack configuration and modify the ArtifactBucket
-parameter so that the instance has access to the release bucket (via the
-IAM Role in the CloudFormation stack).
-
-```shell
-$ cp cloud_formation/parameters/moonshot-sample-app.yml cloud_formation/parameters/moonshot-sample-app-dev-$USER.yml
-```
-
 ## Usage of the CLI
 
 Run the following commands to create your environment and deploy code to it.
@@ -95,12 +86,13 @@ You can now deploy your software to a new stack with:
 $ moonshot create
 ```
 
-By default, you'll get a development environment named `moonshot-sample-app`. If you want to provision test or production
+By default, you'll get a development environment named
+`moonshot-sample-app`. If you want to provision test or production
 named environment, use:
 
 ```shell
-$ moonshot create -n my-service-staging
-$ moonshot create -n my-service-production
+$ moonshot create -n staging
+$ moonshot create -n production
 ```
 
 By default, create launches the stack and deploys code. If you want to only

docs/index.md

@@ -3,21 +3,28 @@ _Because releasing services shouldn't be a moonshot._
 
 ## Overview
 
-Moonshot is a Ruby gem for provisioning environments in AWS using a CLI.
-The environments are centered around a single CloudFormation stack and supported
-by pluggable systems:
-
-- A DeploymentMechanism controls releasing code.
-- A BuildMechanism creates a release artifact.
-- A ArtifactRepository stores the release artifacts.
+Moonshot is a command line tool and library for provisioning and
+managing application environments using CloudFormation. It has native
+support for integration with S3 and CodeDeploy, as well. Other systems
+may be added using our pluggable system. The core components are:
+
+- A DeploymentMechanism controls releasing code. For example, Amazon
+  CodeDeploy.
+- A BuildMechanism creates a release artifact. For example, a local
+  shell script.
+- A ArtifactRepository stores the release artifacts. For example,
+  Amazon S3.
 
 ![General Flow](moonshot.png "General Flow")
 
 ## Design Goals
 
-These are core ideas to the creation of this project. Not all are met to the
-level we'd like (e.g. CloudFormation isn't much of a Choice currently), but we
-should aspire to meet them with each iteration.
+The goal of Moonshot is to wrap CloudFormation in a toolchain that
+codifies the deployment and management of a service. Our goal is that
+within a given service the Moonshot configuration, CloudFormation
+template, and supporting AWS services should be easily understood.
+
+Some of our original design goals were:
 
 - Simplicity: It shouldn't take more than a few hours to understand what your
   release tooling does.
@@ -26,11 +33,6 @@ should aspire to meet them with each iteration.
 - Verbosity: The output of core Moonshot code should explain in detail what
   changes are being made, so knowledge is shared and not abstracted.
 
-## Existing limitations
-
-- Moonshot does not support detailed error logging from Cloudformation substacks.
-- Moonshot does not support a non-local cloudformation file.
-
 ## Installation
 
 You can install Moonshot for your local user with:
@@ -52,17 +54,19 @@ the [example documentation](example.md) as described below to dig in!
 ## Getting started
 
 The Moonshot tool has been designed to be an extensible library for
-your specific use-case. Interested in how it can be used? See
-our [example documentation](example.md). The example doc uses the
-files shown in the
-[sample directory](https://github.com/acquia/moonshot/tree/master/sample) so
-you can figure out how to modify this for your own deployment
-strategy.
+your specific use-case. We aren't trying to solve every use case, but
+rather give you an extensible toolkit that your project can grow with,
+without leaving your trapped behind rigid design philosophy.
+Interested in how it can be used? See our [example documentation][2].
+The example doc uses the files shown in the [sample directory][3] so
+you can figure out how to modify this for your own application.
 
 We also want to [help you contribute and answer all your questions][1]
 on how Moonshot is maintained.
 
 [1]: http://moonshot.readthedocs.org/en/latest/about/contribute
+[2]: example.md
+[3]: https://github.com/acquia/moonshot/tree/master/sample
 
 ## Requirements