more doc updates

Author: Gabriel Monroy

docs/gettingstarted/concepts.rst

@@ -8,7 +8,7 @@ Concepts
 ========
 
 Deis is an application platform that deploys and scales `Twelve Factor`_ apps 
-using a formation of `Chef`_ nodes, `Docker`_ containers and `Nginx`_ proxies.
+using formations of `Chef`_ nodes, `Docker`_ containers and `Nginx`_ proxies.
 
 Formations
 ----------
@@ -25,31 +25,28 @@ easily.  Formations have two primary types of layers.
 
 Runtime Layers
 ^^^^^^^^^^^^^^
-Runtime layers service requests and run background tasks for the formation.
-Nodes in a runtime layer use a `Chef Databag`_  to deploy
-:ref:`Containers <container>` running a specific :ref:`Release`.  
+Runtime layers host :ref:`Containers <container>` for a formation.
+Nodes in a runtime layer use a `Chef Databag`_ to deploy containers for 
+each :ref:`application` in the formation.
 
 Proxy Layers
 ^^^^^^^^^^^^
-Proxy layers expose the formation to the outside world.
+Proxy layers expose :ref:`Applications <application>` to the outside world.
 Nodes in a proxy layer use a `Chef Databag`_ to configure routing of 
 inbound requests to :ref:`Containers <container>` hosted on runtime layers.
 
 Applications
 ------------
-
-An :ref:`application` lives on a :ref:`formation` where it services requests 
-and runs background jobs for a deployed git repository. Each application includes 
-:ref:`Containers <container>` used to run isolated processes, and a 
-:ref:`Release` that defines the current :ref:`Build` and :ref:`config` 
-deployed by containers. 
-
-Developers can use :ref:`Applications <application>` to push builds, change config
-and scale containers without worrying about the formation's underlying infrastructure. 
+An :ref:`application` lives on a :ref:`formation` where it uses 
+:ref:`Containers <container>` to process requests and run background jobs
+for a deployed git repository.
+Developers use :ref:`Applications <application>` to push code, change config,
+scale containers, view logs, or run admin commands --
+regardless of the formation's underlying infrastructure. 
 
 Build, Release, Run
 ------------------- 
-Deis enforces strict separation between Build, Release and Run stages
+Deis enforces strict separation between Build and Run stages
 following the `Twelve Factor model`_.
 
 Build Stage
@@ -72,19 +69,20 @@ config is changed, making it easy to rollback code and configuration.
 Run Stage
 ^^^^^^^^^
 The run stage updates Chef databags and `converges`_ all nodes in the formation.
-The databag specifies the current release, the placement of containers across 
-the runtime layer, and the configuration of the proxy layer.
-SSH is used to converge all of the nodes in the runtime layer followed 
-by all of the nodes in the proxy layer, making zero downtime deployment possible.
+The databag specifies the current application releases, 
+the placement of containers across the runtime layer, 
+and the configuration of the proxy layer.
+SSH is used to converge nodes in runtime layers followed 
+by nodes in proxy layers, making zero downtime deployment possible.
 
 Backing Services
 ----------------
 In keeping with `Twelve Factor`_ methodology, `backing services`_ like
 databases, queues and storage are decoupled and attached using `environment
-variables`_.  This allows formations to use backing services provided via
-different formations (through their proxy layer), or external/third-party 
-services accessible over the network.  The use of environment variables
-also allows formations to easily swap backing services when necessary.
+variables`_.  This allows applications to use backing services provided by
+other applications, or external/third-party services accessible over the network.  
+The use of environment variables makes it easy to swap backing services
+when necessary.
 
 See Also
 --------

docs/gettingstarted/installation.rst

@@ -1,5 +1,5 @@
 :title: Installation
-:description:  Install your own Deis platform on EC2. Configure the Chef server, provision a Deis controller, install the Deis Client and create & scale a formation.
+:description:  Install your own Deis platform on EC2. Provision a Deis controller, Install the Deis Client, Create & Scale a Formation, Deploy & Scale an Application.
 
 .. _installation:
 
@@ -89,6 +89,7 @@ Registration will discover SSH keys automatically and use the
     $ deis register http://my-deis-controller.fqdn
     username: myuser
     password:
+    password (confirm):
     email: myuser@example.com
     Registered myuser
     Logged in as myuser
@@ -109,13 +110,12 @@ Registration will discover SSH keys automatically and use the
 Use the Deis client to create a new formation named "dev" that
 has a default layer that serves as both runtime (hosts containers)
 and proxy (routes traffic to containers).  Scale the default layer
-up to two nodes.
+up to one node.
 
 .. code-block:: console
 
     $ deis formations:create dev --flavor=ec2-us-west-2
     Creating formation... done, created dev
-    
     Creating runtime layer... done in 1s
     
     Use `deis nodes:scale dev runtime=1` to scale a basic formation
@@ -138,9 +138,9 @@ To deploy the application, use ``git push deis master``.
 Deis will automatically deploy Docker containers and configure Nginx proxies
 to route requests to your application.
 
-Once your application is deployed, you use ``deis scale web=4`` to 
+Once your application is deployed, use ``deis scale web=4`` to 
 scale up web containers.  You can also use ``deis logs`` to view 
-aggregated application logs, or ``deis run`` to run one-off admin
+aggregated application logs, or ``deis run`` to run admin
 commands inside your application.
 
 To learn more, use ``deis help`` or browse `the documentation`_.
@@ -150,6 +150,7 @@ To learn more, use ``deis help`` or browse `the documentation`_.
     $ deis create --formation=dev
     Creating application... done, created peachy-waxworks
     Git remote deis added
+    
     $ git push deis master
     Counting objects: 146, done.
     Delta compression using up to 8 threads.
@@ -169,9 +170,9 @@ To learn more, use ``deis help`` or browse `the documentation`_.
            Launching... done, v2
 
     -----> peachy-waxworks deployed to Deis
-           http://ec2-54-214-143-104.us-west-2.compute.amazonaws.com ...
+           http://peachy-waxworks.deisapp.com ...
 
-    $ curl -s http://ec2-54-214-143-104.us-west-2.compute.amazonaws.com
+    $ curl -s http://peachy-waxworks.deisapp.com
     Powered by Deis!
     
     $ deis scale web=4
@@ -181,10 +182,10 @@ To learn more, use ``deis help`` or browse `the documentation`_.
     === peachy-waxworks Containers
     
     --- web: `node server.js`
-    web.1 up 2013-09-23T19:02:30.745Z (dev-runtime-2)
+    web.1 up 2013-09-23T19:02:30.745Z (dev-runtime-1)
     web.2 up 2013-09-23T19:36:48.741Z (dev-runtime-1)
     web.3 up 2013-09-23T19:36:48.758Z (dev-runtime-1)
-    web.4 up 2013-09-23T19:36:48.771Z (dev-runtime-2)
+    web.4 up 2013-09-23T19:36:48.771Z (dev-runtime-1)
 
 
 .. _`Git`: http://git-scm.com

docs/terms/build.rst

@@ -1,12 +1,11 @@
 :title: Build
-:description: A Deis build refers to the output of a specific application build. Deis builds are created automatically using git push.
+:description: Deis builds are created automatically on the controller when a developer uses git push.
 :keywords: build, release, git, git push, deis
 
 .. _build:
 
 Build
 =====
-A Deis build refers to the output of a specific application build.
 Deis builds are created automatically on the controller when a 
 developer uses ``git push deis master``.
 

docs/terms/controller.rst

@@ -13,8 +13,7 @@ the application platform.  A single controller manages multiple
 container formations.
 
 Controllers are tied to a configuration management backend (typically a 
-Chef Server) where data about users, applications and formations 
-is stored and updated.
+Chef Server) where data about users, applications and formations is stored.
 
 The controller is in charge of:
 

docs/terms/formation.rst

@@ -1,11 +1,11 @@
 :title: Formation
-:description: A Deis formation is a set of infrastructure used to host applications and services
+:description: A Deis formation is a set of infrastructure used to host applications.
 :keywords: formation, deis
 
 .. _formation:
 
 Formation
 =========
-A :ref:`formation` is a set of infrastructure used to host :ref:`Applications <application>`
-and services. Each formation includes :ref:`Layers <layer>` of :ref:`Nodes <node>`,
-and is managed by a single :ref:`Controller`.
+A :ref:`formation` is a set of infrastructure used to host :ref:`Applications <application>`.
+Each formation includes :ref:`Layers <layer>` of :ref:`Nodes <node>` 
+that provide different services to the formation.

docs/terms/layer.rst

@@ -13,14 +13,14 @@ easily.
 
 Runtime Layers
 ^^^^^^^^^^^^^^
-Runtime layers service requests and run background tasks for the formation.
-Nodes in a runtime layer use a configuration management system (e.g. Chef Server)
-to deploy :ref:`Containers <container>` running a specific :ref:`Release`.
+Runtime layers host :ref:`Containers <container>` for a formation.
+Nodes in a runtime layer use a `Chef Databag`_ to deploy containers for 
+each :ref:`application` in the formation.
 
 Proxy Layers
 ^^^^^^^^^^^^
-Proxy layers expose the formation to the outside world.
-Nodes in a proxy layer use configuration management to configure routing of 
+Proxy layers expose :ref:`Applications <application>` to the outside world.
+Nodes in a proxy layer use a `Chef Databag`_ to configure routing of 
 inbound requests to :ref:`Containers <container>` hosted on runtime layers.
 
 Dual Layers
@@ -34,3 +34,5 @@ Custom Layers
 It is also possible to create custom layers that don't provide runtime or proxy
 services to the formation.  This is useful for scaling and managing backing
 services built with Chef that need to be managed alongside a formation.
+
+.. _`Chef Databag`: http://docs.opscode.com/essentials_data_bags.html