README.md in stairs-0.4.2 vs README.md in stairs-0.5.0

@@ -1,15 +1,24 @@
 # Stairs
 
-It's a pain to setup new developers. Stairs is a utility and framework from
-which to write scripts for faster and easier setup of apps in new development
-environments. Scripts try to automate as much as possible and provide
-interactive prompts for everything else.
+It's a pain to set up new developers on your codebase. Stairs makes it easy.
 
-Stairs currently supports writing environment variables for rbenv-vars, RVM,
-and dotenv.
+### The Problem
 
+Apps these days come with dependencies—S3, Facebook, Twitter, Zencoder, etc. We
+can stub certain things in development, but we also want to make sure we're
+developing in a realistic setting. Satisfying all of these requirements can
+really slow down onboarding time when adding new developers to your existing
+codebase.
+
+### The Solution
+
+Every codebase should come with a script to set itself up. An interactive
+README, if you will. __Stairs__ aims to provide the tools to make writing these
+scripts fast and easy. Scripts try to automate as much as possible and provide
+interactive prompts for everything else.
+
 [![Build Status](https://travis-ci.org/patbenatar/stairs.png?branch=master)](https://travis-ci.org/patbenatar/stairs)
 [![Code Climate](https://codeclimate.com/github/patbenatar/stairs.png)](https://codeclimate.com/github/patbenatar/stairs)
 
 ## Setup
 
@@ -60,42 +69,12 @@
 rake "db:setup"
 
 finish "Just run rails s and sidekiq to get rolling!"
 ```
 
-### Example CLI
+[See Example CLI](#example-cli)
 
-Given the above script, the CLI might look like this.
-
-```
-$ rake newb
-Looks like you're using rbenv to manage environment variables. Is this correct? (Y/N): Y
-= Running script setup.rb
-== Running bundle
-...
-== Completed bundle
-== Running S3
-AWS access key: 39u39d9u291
-AWS secret: 19jd920i10is0i01i0s01ks0kfknkje
-Do you have an existing bucket? (Y/N): Y
-Bucket name (leave blank for app-dev): my-cool-bucket
-== Completed S3
-== Starting Zencoder
-This step is optional, would you like to perform it? (Y/N): N
-== Completed Zencoder
-== Starting Misc
-Cool check it value: w00t
-== Completed Misc
-== Running db:setup
-...
-== Completed db:setup
-== All done!
-Run rails s and sidekiq to get rolling!
-```
-
-## DSL
-
 ### Collecting values
 ```ruby
 value = provide "Something"
 value = provide "Another", required: false
 provide "More", default: "a-default"
@@ -109,10 +88,12 @@
 end
 dinner = choice "Meat or vegetables?", ["Meat", "Vegetables"]
 ```
 
 ### Setting env vars
+Stairs currently supports writing environment variables for rbenv-vars, RVM, and dotenv.
+
 ```ruby
 env "NAME", value
 ```
 
 ### Writing files
@@ -153,24 +134,60 @@
 ```
 
 ## Plugins for common setups
 
 ### Built-in
+
 * `:secret_token` sets a secure random secret token
+* `:postgresql` quickly setup database.yml for use with PostgreSQL
+* `:facebook` interactive prompt for setting Facebook app credentials
 
-### Available as extension gems
+### Available as independent gems
+
+Any plugin that has specific dependencies on third party gems is shipped
+independently to avoid maintaining those dependencies within Stairs.
+
 * `:s3` interactive prompt for setting AWS + S3 bucket access credentials:
   [patbenatar/stairs-steps-s3][s3]
 * `:balanced` automatically creates a test Marketplace on Balanced:
   [patbenatar/stairs-steps-balanced][balanced]
-* `:facebook` interactive prompt for setting Facebook app credentials:
-  [patbenatar/stairs-steps-facebook][facebook]
 
 ### Defining custom plugins
 
 Steps inherit from `Stairs::Step` and live in `Stairs::Steps`, have a title,
 description, and implement the `run` method. See those included and in the
 various extension gems for examples.
+
+## Example CLI
+
+Given the [example script above](#defining-scripts), the CLI would look like
+this:
+
+```
+$ rake newb
+Looks like you're using rbenv to manage environment variables. Is this correct? (Y/N): Y
+= Running script setup.rb
+== Running bundle
+...
+== Completed bundle
+== Running S3
+AWS access key: 39u39d9u291
+AWS secret: 19jd920i10is0i01i0s01ks0kfknkje
+Do you have an existing bucket? (Y/N): Y
+Bucket name (leave blank for app-dev): my-cool-bucket
+== Completed S3
+== Starting Zencoder
+This step is optional, would you like to perform it? (Y/N): N
+== Completed Zencoder
+== Starting Misc
+Cool check it value: w00t
+== Completed Misc
+== Running db:setup
+...
+== Completed db:setup
+== All done!
+Run rails s and sidekiq to get rolling!
+```
 
 ## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)