Merge pull request #115 from alecbenson/master

Minor readme adjustments for clarity and readability.

docs/getting-started.md

@@ -3,27 +3,27 @@
 You have an application you want to package up. It's composed of several containers representing microservices.
 
 ## Plan
-1. Find your resources: **container images**. Do you really need your own web server or database image? If you're writing a Dockerfile for a common service try to find a well-known, supported, certified, stable image that you can build on.
-1. Find your resources: **provider orchestration templates**. Here we're talking about kubernetes files (service, replication controller, pod) or OpenShift or Docker Compose files. Related to #1, if you're writing files for common services try to find well-known, supported, certified, stable templates that you can build on.
+1. Find your resources: **container images**. Do you really need your own web server or database image? If you're writing a Dockerfile for a common service, try to find a well-known, supported, certified, stable image that you can build on.
+1. Find your resources: **provider orchestration templates**. Here we're talking about kubernetes files (service, replication controller, pod) or OpenShift or Docker Compose files. Related to #1, if you're writing files for common services, try to find well-known, supported, certified, stable templates that you can build on.
 
 ## Prepare
-From the planning phase you've got a collection of remote and local sources that are going to compose your application.
+From the planning phase, you've got a collection of remote and local sources that your application will be comprised of.
 
 1. Start with the containers. Understand how they run standalone. Get them running.
-1. Orchestrate the containers on the target provider. Start simply and build up. For example, with kubernetes just deploy as a pod. Once that succeeds, add a service, then replication controllers. There are many opportunities for error so make small changes, test and iterate slowly. Verify your [YAML](http://codebeautify.org/yaml-validator) or [JSON](http://jsonlint.com/) frequently. Use a method that can be easily incorporated into your development workflow: small change -> save -> validate -> test -> rinse and repeat.
+1. Orchestrate the containers on the target provider. Start simply and build up. For example, with kubernetes just deploy as a pod. Once that succeeds, add a service, and then some replication controllers. There are many opportunities for error -- so make small changes, test and iterate slowly. Verify your [YAML](http://codebeautify.org/yaml-validator) or [JSON](http://jsonlint.com/) frequently. Use a method that can be easily incorporated into your development workflow: small change -> save -> validate -> test -> rinse and repeat.
 1. Test both custom and stock services together. Nulecule won't do magical things. The pieces must all work together before they can be packaged up as a unit.
 
 ## Package
 Only when everything is working are you ready to package the application. In this phase you'll be interacting with the [Nulecule specification](https://github.com/projectatomic/nulecule/tree/master/spec).
 
 1. Download a [Nulecule template](/spec/0.0.2/examples/template) to start from.
-1. In the Nulecule file create one or more lists of things under `graph`. These represent the different components that make up your application. Names are arbitrary. Remember to verify your [YAML](http://codebeautify.org/yaml-validator) or [JSON](http://jsonlint.com/) frequently.
-    1. If they are remote sources all that is needed is a name and source. Remote sources are other Nulecule applications.
+1. In the Nulecule file, create one or more lists of things under `graph`. These represent the different components that make up your application. Names are arbitrary. Remember to verify your [YAML](http://codebeautify.org/yaml-validator) or [JSON](http://jsonlint.com/) frequently.
+    1. If your sources are remote, then all that is needed is a name and source. Remote sources are other Nulecule applications.
 
             graph:
             - name: mydb
               source: "docker://registry.example.com/some/database"
-    1. If they are local sources then provide a name and an artifacts key that will reference the source file(s). Each provider will have a key specifying the provider. For example, "docker" or "kubernetes".
+    1. If your sources are local, then provide a name and an artifacts key that will reference the source file(s). Each provider will have a key specifying the provider. For example, "docker" or "kubernetes".
 
             graph:
             - name: myapp
@@ -41,7 +41,7 @@ Only when everything is working are you ready to package the application. In thi
         ├── Nulecule
         └── README.md
 
-1. Consider the different ways your application may be deployed. Most likely there are many parameters that need to be exposed at deployment. It's best to overdo this and provide defaults whenever possible. Go through the provider files and change any values. For example `database_pass: changeme` becomes `database_pass: $db_pass`. The name of the parameter is `db_pass`. These go into the params section of the Nulecule file under each provider. For example:
+1. Consider the different ways your application may be deployed. There will likely be many parameters that need to be exposed at deployment. It's best to overdo this and provide defaults whenever possible. Go through the provider files and change any values. For example `database_pass: changeme` becomes `database_pass: $db_pass`. The name of the parameter is `db_pass`. These go into the params section of the Nulecule file under each provider. For example:
 
 
         graph:
@@ -57,7 +57,7 @@ Only when everything is working are you ready to package the application. In thi
     * what does this application do?
     * what provider environment(s) do I need to have setup before I deploy it?
     * how do I verify that it has been deployed correctly?
-1. Add a metadata section, including a name, description and license information. Arbitrary metadata may also be added. Consider using keyword tags, for example, that may be useful for deployment management. For example:
+1. Add a metadata section, including a name, description and license information. Arbitrary metadata may also be added. Consider using keyword tags that may be useful for deployment management. For example:
 
         metadata:
           name: My Cool App
@@ -74,9 +74,9 @@ Only when everything is working are you ready to package the application. In thi
     * yaml or json is not valid
     * missing parameter
 
-1. Once the Nulecule file and provider artifacts are working package the application as a container. Typically this means basing it off of an executable image such as `projectatomic/atomicapp`. Unless you have a special use case, the stock Dockerfile may be used unaltered.
+1. Once the Nulecule file and provider artifacts are working, package the application as a container. Typically, this means basing it off of an executable image such as `projectatomic/atomicapp`. Unless you have a special use case, the stock Dockerfile may be used unaltered.
 
         [sudo] docker build -t mydb-app .
 
 ## Push & Pull
-Push the image to a registry. Tell people about it and see if they can deploy your application without any assistance. If they have questions you probably should enhance the application and parameter descriptions so they are clear.
+Push the image to a registry. Tell people about it and see if they can deploy your application without any assistance. If they have questions, you probably should enhance the application and parameter descriptions so they are clear.