First iteration of the README.

README.md

@@ -1,31 +1,124 @@
-# ActiveModelSerializers
+# ActiveModel::Serializers 
+ 
+[![Build Status](https://travis-ci.org/steveklabnik/active_model_serializers.svg?branch=master)](https://travis-ci.org/steveklabnik/active_model_serializers?branch=master) 
 
-[![Build Status](https://travis-ci.org/steveklabnik/active_model_serializers.svg?branch=master)](https://travis-ci.org/steveklabnik/active_model_serializers?branch=master)
+ActiveModel::Serializers brings convention over configuration to your JSON generation. 
 
-TODO: Write a gem description
+AMS does this through two components: **serializers** and **adapters**. Serializers describe which attributes and relationships should be serialized. Adapters describe how attributes and relationships should be serialized.
 
-## Installation
+## Example
 
-Add this line to your application's Gemfile:
+Given two models, a `Post(title: string, body: text)` and a `Comment(name:string, body:text, post_id:integer)`, you will have two serializers:
 
-    gem 'active_model_serializers'
+```
+class PostSerializer < ActiveModel::Serializer
+  attribute :title, :body
+  
+  has_many :comments
 
-And then execute:
+  url :post
+end
+```
 
-    $ bundle
+and
 
-Or install it yourself as:
+```
+class CommentSerializer < ActiveModel::Serializer
+  attribute :name, :body
+  
+  belongs_to :post_id
+  
+  url [:post, :comment]
+end
+```
 
-    $ gem install active_model_serializers
+Generally speaking, you as a user of AMS will write (or generate) these serializer classes. By default, they will use the JsonApiAdapter, implemented by AMS. If you want to use a different adapter, such as a HalAdapter, you can change this in an initializer:
 
-## Usage
+```
+ActiveModel::Serializer.default_adapter = ActiveModel::Serializer::Adapter::HalAdapter
+```
 
-TODO: Write usage instructions here
+You won't need to implement an adapter unless you wish to use a new format or media type with AMS.
 
-## Contributing
+In your controllers, when you use `render :json`, Rails will now first search
+for a serializer for the object and use it if available.
 
-1. Fork it ( https://github.com/[my-github-username]/active_model_serializers/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+```ruby
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id])
+
+    render json: @post
+  end
+end
+```
+
+In this case, Rails will look for a serializer named `PostSerializer`, and if
+it exists, use it to serialize the `Post`.
+
+## Installation 
+ 
+Add this line to your application's Gemfile: 
+ 
+    gem 'active_model_serializers' 
+ 
+And then execute: 
+ 
+    $ bundle 
+
+## Creating a Serializer
+
+The easiest way to create a new serializer is to generate a new resource, which
+will generate a serializer at the same time:
+
+```
+$ rails g resource post title:string body:string
+```
+
+This will generate a serializer in `app/serializers/post_serializer.rb` for
+your new model. You can also generate a serializer for an existing model with
+the serializer generator:
+
+```
+$ rails g serializer post
+```
+
+The generated seralizer will contain basic `attributes` and `has_many`/`belongs_to` declarations, based on
+the model. For example:
+
+```
+class PostSerializer < ActiveModel::Serializer
+  attribute :title, :body
+  
+  has_many :comments
+
+  url :post
+end
+```
+
+and
+
+```
+class CommentSerializer < ActiveModel::Serializer
+  attribute :name, :body
+  
+  belongs_to :post_id
+  
+  url [:post, :comment]
+end
+```
+
+The attribute names are a **whitelist** of attributes to be serialized. 
+ 
+The `has_many` and `belongs_to` declarations describe relationships between resources. By default, when you serialize a `Post`, you will
+get its `Comment`s as well.
+
+The `url` declaration describes which named routes to use while generating URLs for your JSON. Not every adapter will require URLs.
+ 
+## Contributing 
+ 
+1. Fork it ( https://github.com/rails-api/active_model_serializers/fork ) 
+2. Create your feature branch (`git checkout -b my-new-feature`) 
+3. Commit your changes (`git commit -am 'Add some feature'`) 
+4. Push to the branch (`git push origin my-new-feature`) 
+5. Create a new Pull Request