From c7c9a03c4e9b5000c7b34f401a4561063998e624 Mon Sep 17 00:00:00 2001
From: Benjamin Fleischer <github@benjaminfleischer.com>
Date: Sun, 13 Dec 2015 16:10:52 -0600
Subject: [PATCH] Touch ups

---
 README.md                               |  7 +++++--
 docs/README.md                          | 13 +-----------
 docs/general/adapters.md                | 27 ++++---------------------
 docs/general/caching.md                 |  2 ++
 docs/general/configuration_options.md   |  2 ++
 docs/general/getting_started.md         |  2 ++
 docs/general/instrumentation.md         |  3 +++
 docs/general/logging.md                 |  6 ++++--
 docs/{howto => general}/rendering.md    |  0
 docs/general/serializers.md             | 12 ++++++-----
 docs/howto/add_pagination_links.md      |  2 ++
 docs/howto/outside_controller_use.md    |  6 ++++--
 docs/integrations/ember-and-json-api.md |  2 ++
 docs/jsonapi/schema.md                  |  2 ++
 14 files changed, 40 insertions(+), 46 deletions(-)
 rename docs/{howto => general}/rendering.md (100%)

diff --git a/README.md b/README.md
index 1ea017dd5..e6b79d253 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,8 @@ architecture. We'd love your help. [Learn how you can help here.](https://github
 
 ## Installation
 
+Note: *ActiveModelSerializers is already included on Rails >= 5*
+
 Add this line to your application's Gemfile:
 
 ```
@@ -61,11 +63,12 @@ And then execute:
 $ bundle
 ```
 
-*ActiveModelSerializers is already included on Rails >= 5*
+## Getting Started
+
+See [Getting Started](docs/general/getting_started.md) for the nuts and bolts.
 
 ## High-level behavior
 
-See [Getting Started](docs/general/getting_started.md) for the nuts and bolts:
 
 Given a [serializable model](lib/active_model/serializer/lint.rb):
 
diff --git a/docs/README.md b/docs/README.md
index 1caadfe69..7256b108f 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,6 +14,7 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 - [Caching](general/caching.md)
 - [Logging](general/logging.md)
 - [Instrumentation](general/instrumentation.md)
+- [JSON API Schema](jsonapi/schema.md)
 
 ## How to
 
@@ -29,15 +30,3 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 | Grape | 0.10.x + | [#1258](https://github.com/rails-api/active_model_serializers/issues/1258)  |
 | Grape | 0.9.x | https://github.com/jrhe/grape-active_model_serializers/ |
 | Sinatra | 0.9.x | https://github.com/SauloSilva/sinatra-active-model-serializers/
-
-## Getting Help
-
-If you find a bug, please report an [Issue](https://github.com/rails-api/active_model_serializers/issues/new).
-
-If you have a question, please [post to Stack Overflow](http://stackoverflow.com/questions/tagged/active-model-serializers).
-
-Thanks!
-
-## Contributing
-
-See [CONTRIBUTING.md](https://github.com/rails-api/active_model_serializers/blob/master/CONTRIBUTING.md)
diff --git a/docs/general/adapters.md b/docs/general/adapters.md
index 4d5dcc62b..daee3b8be 100644
--- a/docs/general/adapters.md
+++ b/docs/general/adapters.md
@@ -1,3 +1,5 @@
+[Back to Guides](../README.md)
+
 # Adapters
 
 ActiveModelSerializers offers the ability to configure which adapter
@@ -28,7 +30,7 @@ The local adapter option is in the format `adapter: adapter`, where `adapter` is
 any of the same values as set globally.
 
 The configured adapter can be set as a symbol, class, or class name, as described in
-[Advanced adapter configuration](adapters.md#Advanced adapter configuration).
+[Advanced adapter configuration](adapters.md#advanced-adapter-configuration).
 
 The `Attributes` adapter does not include a root key. It is just the serialized attributes.
 
@@ -51,7 +53,7 @@ Doesn't follow any specific convention.
 
 ### JSON API
 
-This adapter follows **version 1.0** of the format specified in
+This adapter follows **version 1.0** of the [format specified](../jsonapi/schema.md) in
 [jsonapi.org/format](http://jsonapi.org/format).
 
 #### Included
@@ -107,27 +109,6 @@ The user could pass in `include=**`.
 
 We recommend filtering any user-supplied includes appropriately.
 
-## Choosing an adapter
-
-If you want to use a specify a default adapter, such as JsonApi, you can change this in an initializer:
-
-```ruby
-ActiveModelSerializers.config.adapter = ActiveModel::Serializer::Adapter::JsonApi
-```
-
-or
-
-```ruby
-ActiveModelSerializers.config.adapter = :json_api
-```
-
-If you want to have a root key for each resource in your responses, you should use the Json or
-JsonApi adapters instead of the default Attributes:
-
-```ruby
-ActiveModelSerializers.config.adapter = :json
-```
-
 ## Advanced adapter configuration
 
 ### Registering an adapter
diff --git a/docs/general/caching.md b/docs/general/caching.md
index f2db7b943..7d02568a3 100644
--- a/docs/general/caching.md
+++ b/docs/general/caching.md
@@ -1,3 +1,5 @@
+[Back to Guides](../README.md)
+
 # Caching
 
 To cache a serializer, call ```cache``` and pass its options.
diff --git a/docs/general/configuration_options.md b/docs/general/configuration_options.md
index 52f7c4081..81d03bb86 100644
--- a/docs/general/configuration_options.md
+++ b/docs/general/configuration_options.md
@@ -1,3 +1,5 @@
+[Back to Guides](../README.md)
+
 # Configuration Options
 
 The following configuration options can be set on `ActiveModelSerializers.config`,
diff --git a/docs/general/getting_started.md b/docs/general/getting_started.md
index 70eca9479..91e74c09d 100644
--- a/docs/general/getting_started.md
+++ b/docs/general/getting_started.md
@@ -1,3 +1,5 @@
+[Back to Guides](../README.md)
+
 # Getting Started
 
 ## Creating a Serializer
diff --git a/docs/general/instrumentation.md b/docs/general/instrumentation.md
index 160a9e765..ba6a1ffd8 100644
--- a/docs/general/instrumentation.md
+++ b/docs/general/instrumentation.md
@@ -1,3 +1,5 @@
+[Back to Guides](../README.md)
+
 # Instrumentation
 
 ActiveModelSerializers uses the
@@ -30,6 +32,7 @@ ActiveSupport::Notifications.subscribe 'render.active_model_serializers' do |*ar
   # event.payload
   # whatever
 end
+```
 
 ## [LogSubscriber](http://api.rubyonrails.org/classes/ActiveSupport/LogSubscriber.html)
 
diff --git a/docs/general/logging.md b/docs/general/logging.md
index 010ae01a1..a37e5d9fb 100644
--- a/docs/general/logging.md
+++ b/docs/general/logging.md
@@ -1,11 +1,13 @@
+[Back to Guides](../README.md)
+
 # Logging
 
-If we are using ActiveModel::Serializers on Rails app by default the `Rails.logger` will be used.
+If we are using ActiveModelSerializers on a Rails app by default the `Rails.logger` will be used.
 
 On a non Rails enviroment by default the `ActiveSupport::TaggedLogging` will be
 used.
 
-If we need to customize the logger we can define this in an initializer:
+You may customize the logger we by in an initializer, for example:
 
 ```ruby
 ActiveModelSerializers.logger = Logger.new(STDOUT)
diff --git a/docs/howto/rendering.md b/docs/general/rendering.md
similarity index 100%
rename from docs/howto/rendering.md
rename to docs/general/rendering.md
diff --git a/docs/general/serializers.md b/docs/general/serializers.md
index 900a97486..fb121e379 100644
--- a/docs/general/serializers.md
+++ b/docs/general/serializers.md
@@ -1,3 +1,5 @@
+[Back to Guides](../README.md)
+
 # Serializers
 
 Given a serializer class:
@@ -27,10 +29,10 @@ Serialization of the resource `title`
 
 | In Serializer               | #attributes |
 |---------------------------- |-------------|
-| `attribute :title`          | { title: 'Some Title' } `
-| `attribute :title, key: :name` | { name: 'Some Title' } `
-| `attribute :title { 'A Different Title'}` | { title: 'A Different Title' } `
-| `attribute :title`<br>`def title 'A Different Title' end` | { title: 'A Different Title' }`
+| `attribute :title`          | `{ title: 'Some Title' } `
+| `attribute :title, key: :name` | `{ name: 'Some Title' } `
+| `attribute :title { 'A Different Title'}` | `{ title: 'A Different Title' } `
+| `attribute :title`<br>`def title 'A Different Title' end` | `{ title: 'A Different Title' }`
 
 
 ### Associations
@@ -139,7 +141,7 @@ class CommentSerializer < ActiveModel::Serializer
 end
 ```
 
-Generally speaking, you as a user of ActiveModelSerializers will write (or generate) these
+Generally speaking, you, as a user of ActiveModelSerializers, will write (or generate) these
 serializer classes.
 
 ## More Info
diff --git a/docs/howto/add_pagination_links.md b/docs/howto/add_pagination_links.md
index ae1bd925f..237b44ae9 100644
--- a/docs/howto/add_pagination_links.md
+++ b/docs/howto/add_pagination_links.md
@@ -1,3 +1,5 @@
+[Back to Guides](../README.md)
+
 # How to add pagination links
 
 ### JSON API adapter
diff --git a/docs/howto/outside_controller_use.md b/docs/howto/outside_controller_use.md
index 62c876740..a83a69cad 100644
--- a/docs/howto/outside_controller_use.md
+++ b/docs/howto/outside_controller_use.md
@@ -1,3 +1,5 @@
+[Back to Guides](../README.md)
+
 ## Using ActiveModelSerializers Outside Of A Controller
 
 ### Serializing a resource 
@@ -18,7 +20,7 @@ serializable_resource = ActiveModel::SerializableResource.new(post, options)
 model_json = serializable_resource.as_json
 ``` 
 
-### Retrieving a Resource's Active Model Serializer
+### Looking up the Serializer for a Resource
 
 If you want to retrieve a serializer for a specific resource, you can do the following:
 
@@ -39,4 +41,4 @@ You could also retrieve the serializer via:
 ActiveModel::SerializableResource.new(post, options).serializer 
 ```
 
-Both approaches will return an instance, if any, of the resource's serializer.
\ No newline at end of file
+Both approaches will return an instance, if any, of the resource's serializer.
diff --git a/docs/integrations/ember-and-json-api.md b/docs/integrations/ember-and-json-api.md
index 381c39edb..bd4fa4c0e 100644
--- a/docs/integrations/ember-and-json-api.md
+++ b/docs/integrations/ember-and-json-api.md
@@ -1,3 +1,5 @@
+[Back to Guides](../README.md)
+
 # Integrating with Ember and JSON API
 
  - [Preparation](./ember-and-json-api.md#preparation)
diff --git a/docs/jsonapi/schema.md b/docs/jsonapi/schema.md
index 1a42585b3..72b149484 100644
--- a/docs/jsonapi/schema.md
+++ b/docs/jsonapi/schema.md
@@ -1,3 +1,5 @@
+[Back to Guides](../README.md)
+
 [![JSON API 1.0](https://img.shields.io/badge/JSON%20API-1.0-lightgrey.svg)](http://jsonapi.org/)
 
 ## JSON API Requests