README.md in smooth-2.0.1 vs README.md in smooth-2.0.2

@@ -1,9 +1,158 @@
 # Smooth
 
-TODO: Write a gem description
+Smooth provides a way of developing JSON APIs on top of SQL Databases that is, well, smooth. 
 
+Smooth provides a ruby library and a front end graphical application
+that make the process of developing APIs for your web and mobile
+applications really productive. 
+
+#### General idea: in the abstract
+
+A resource is, generally, a database backed collection of models. A
+resource can be accessed by users who have different roles and relations
+to the data.  A resource is accessed in one of two ways: queries, and
+commands.  The resource can be presented in different views.
+
+#### The benefits of a declarative, data driven programming style
+
+As a developer you get API interface inspection capabilities 
+for free by coding your API in the smooth style.  These capabilities can give you a lot of power 
+for your every day development practice.
+
+Generating documentation, generating custom querying and reporting
+tools, generating API client libraries, generating automated test code,
+and a number of other tasks become much much easier.
+
+#### The Smooth approach starts with declarations
+
+In smooth we develop resources by describing or declaring data about the
+different functions an API client will need access to to provide its
+users the means of interacting with their data that they need.
+
+##### Commands:
+
+Commands handle API requests whose intent is to change data in the
+resource. A user updating their profile. A person adding a new recipe
+to their cookbook. A moderator removing a rude comment on their blog. 
+
+We define the set of commands available and what information they
+require:
+
+- In what ways can a user change the data?
+- What specific parameters must an API client pass to these commands?
+- Describe what they mean for a developer?
+- What type of data, what values?
+
+##### Queries:
+
+API clients often have large sets of data that they need to reduce to a  
+manageable size to render in some view in their application or dynamic
+page on their website.
+
+- In what ways can a user or role filter the data? 
+- Specifically what parameters would an API client pass? 
+- What type of data, what values?
+- Should a user only be allowed to see a hard coded subset of records? 
+
+##### Serializers:
+
+Given a query which returns a set of zero or more records, we will often
+want to present this data in an optimized format.  We'll want to convert 
+a specific timestamp into a description of the amount of time that has
+passed.  We'll want to display individual things in a table, or maybe as a pie chart. 
+
+In smooth we enumerate:
+
+- In what ways would an API client want to see this data? 
+- As individual objects? As a reduced / aggregated report?
+- In what ways does the data change depending on who is looking at it?
+- Are there different serializers for different roles?
+- What are each of the attributes and what do they mean?
+
+## Coding the smooth way 
+
+There are a few distinctly different ways of working with code *sunglasses* smoothly.
+
+- Use it in your rails application, edit the different classes of ruby
+  objects whose file names, locations, and class names follow a familiar
+  naming convention.
+
+- Use it in a standalone ruby application as a rack compatible
+  application or middleware.  File organization and class naming approach
+  follows same familiar naming conventions.
+
+- Use the DSL to build an entire application from one or more configuration
+  files organized however you want.
+
+- Use the smooth developer mode to build the structure of your API and
+  resources visually and from a user interface.  Customize small methods
+  with configuration, and if necessary, custom code.
+
+- Use the smooth developer mode and don't write any code at all.
+  (Obviously you are limited in what you can do with this approach, but
+  for simple apps this is often effective.)
+
+### Example Code
+
+```
+# Sample App Structure (Rails or Standalone)
+
+- app
+  - models
+    - book.rb
+  - commands
+    - create_book.rb
+    - update_book.rb
+  - queries
+    - book_query.rb
+  - serializers
+    - book_serializer.rb
+    - book_summary_serializer.rb
+```
+
+#### Queries
+
+```ruby
+class BookQuery < Smooth::Query
+  params do
+    desc "Filter the books by a wildcard title"
+    string :title_is_like, operator: "like"
+
+    desc "Filter the books published after a certain year"
+    integer :published_after_year, operator: "greater_than_or_equal_to", min_length: 4
+  end
+end
+```
+
+Run the query:
+
+```ruby
+BookQuery.as(current_user).query_with(params) #=> Book: ActiveRecord::Relation
+```
+
+Inspect the query interface:
+
+```
+BookQuery.interface 
+
+{
+  optional_parameters:{
+    "title_is_like": {
+      description: "Filter the books by wildcard title" 
+    }
+  }
+}
+```
+
+### TODO: Command Example 
+### TODO: Serializers Example
+### TODO: Router Example
+### TODO: Backbone + Ember Data Model Generator
+### TODO: Interactive API Documentation Generator
+### TODO: Objective-C CoreData Configuration Generator 
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
     gem 'smooth'
@@ -13,13 +162,9 @@
     $ bundle
 
 Or install it yourself as:
 
     $ gem install smooth
-
-## Usage
-
-TODO: Write usage instructions here
 
 ## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)