creating initial general and how to docs

Author: joaomdmoura

docs/general/adapters.md

@@ -0,0 +1,52 @@
+# Adapters
+
+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.
+You can use one of the built-in adapters (```FlattenJSON``` is the default one) or create one by your one but you won't need to implement an adapter unless you wish to use a new format or
+media type with AMS.
+
+## Built in Adapters
+
+### FlattenJSON - Default
+
+It's the default adapter, it generates a json response without a root key.
+Doesn't follow any specifc convention.
+
+### JSON
+
+It also generates a json response but always with a root key. The root key **can't be overridden**, and will be automatically defined accordingly with the objects being serialized.
+Doesn't follow any specifc convention.
+
+### JSONAPI
+
+This adapter follows 1.0 of the format specified in
+[jsonapi.org/format](http://jsonapi.org/format). It will include the associated
+resources in the `"included"` member when the resource names are included in the
+`include` option.
+
+```ruby
+  render @posts, include: ['authors', 'comments']
+  # or
+  render @posts, include: 'authors,comments'
+```
+
+## Choose an Adapter
+
+If you want to use a different adapter, such as a JsonApi, you can change this in an initializer:
+
+```ruby
+ActiveModel::Serializer.config.adapter = ActiveModel::Serializer::Adapter::JsonApi
+```
+
+or
+
+```ruby
+ActiveModel::Serializer.config.adapter = :json_api
+```
+
+If you want to have a root key on your responses you should use the Json adapter, instead of the default FlattenJson:
+
+```ruby
+ActiveModel::Serializer.config.adapter = :json
+```

docs/general/getting_started.md

@@ -0,0 +1,75 @@
+# Getting Started
+
+## Installation
+
+### ActiveModel::Serializer is already included on Rails >= 5
+
+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`/`has_one`/`belongs_to` declarations, based on the model. For example:
+
+```ruby
+class PostSerializer < ActiveModel::Serializer
+  attributes :title, :body
+
+  has_many :comments
+  has_one :author
+
+  url :post
+end
+```
+
+and
+
+```ruby
+class CommentSerializer < ActiveModel::Serializer
+  attributes :name, :body
+
+  belongs_to :post_id
+
+  url [:post, :comment]
+end
+```
+
+## Rails Integration
+
+AMS will automatically integrate with you Rails app, you won't need to update your controller, this is a example of how it will look like:
+
+```ruby
+class PostsController < ApplicationController
+
+  def show
+    @post = Post.find(params[:id])
+    render json: @post
+  end
+
+end
+```

docs/howto/add_root_key.md

@@ -0,0 +1,56 @@
+# How to use add root key
+
+Add the root key to your API is quite simple with AMS. The **Adapter** is what determines the format of your JSON response. The default adapter is the ```FlattenJSON``` which doesn't have the root key, so your response is something similar to:
+
+```json
+{
+  id: 1,
+  title: "Awesome Post Tile",
+  content: "Post content"
+}
+```
+
+In order to add the correspondent root key you need to use the ```JSON``` Adapter, you can change this in an initializer:
+
+```ruby
+ActiveModel::Serializer.config.adapter = :json_api
+```
+
+or
+
+```ruby
+ActiveModel::Serializer.config.adapter = ActiveModel::Serializer::Adapter::Json
+```
+
+This will add the root key to all your serialized endpoints.
+
+ex:
+
+```json
+{
+  post: {
+    id: 1,
+    title: "Awesome Post Tile",
+    content: "Post content"
+  }
+}
+```
+
+or if it returns a collection:
+
+```json
+{
+  posts: [
+    {
+      id: 1,
+      title: "Awesome Post Tile",
+      content: "Post content"
+    },
+    {
+      id: 2,
+      title: "Another Post Tile",
+      content: "Another post content"
+    }
+  ]
+}
+```