edits and rearranging logic

docs/README.md

@@ -16,7 +16,6 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 - [Instrumentation](general/instrumentation.md)
 - [JSON API Schema](jsonapi/schema.md)
 - [ARCHITECTURE](ARCHITECTURE.md)
-- [Passing Arbitrary Options](general/passing_arbitrary_options.md)
 
 ## How to
 
@@ -24,6 +23,7 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 - [How to add pagination links](howto/add_pagination_links.md)
 - [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md)
 - [Testing ActiveModelSerializers](howto/test.md)
+- [Passing Arbitrary Options](how-to/passing_arbitrary_options.md)
 
 ## Integrations
 

docs/general/passing_arbitrary_options.md

@@ -1,45 +0,0 @@
-[Back to Guides](../README.md)
-
-# Passing Arbitrary Options To A Serializer
-
-Let's say you have a basic Post Controller:
-
-```ruby
-class PostController < ApplicationController
-  def dashboard  
-    render json: @posts
-  end
-end
-```
-
-Odds are, your serializer will look something like this:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-end
-```
-
-This works all fine and well, but maybe you passing in some arbitrary options
-into the serializer. These options can be anything that isn't already reserved for use by
-ActiveModelSerializers' adapter options.
-
-Here's an example:
-
-```ruby
-# posts_controller.rb
-class PostController < ApplicationController
-  def dashboard  
-    render json: @posts, user_id: 12
-  end
-end
-
-# post_serializer.rb
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-
-  def comments_by_me  
-    Comments.where(user_id: instance_options[:user_id], post_id: object.id)
-  end
-end
-```

docs/howto/passing_arbitrary_options.md

@@ -0,0 +1,30 @@
+[Back to Guides](../README.md)
+
+# Passing Arbitrary Options To A Serializer
+
+In addition to the [`serialization_scope`](../general/serializers.md#scope), any options passed to `render`
+that are not reserved for the [adapter](../general/rendering.md#adapter_opts)
+are available in the serializer as [instance_options](../general/serializers.md#instance_options).
+
+For example, we could pass in a field, such as `user_id` into our serializer.
+
+```ruby
+# posts_controller.rb
+class PostsController < ApplicationController
+  def dashboard  
+    render json: @post, user_id: 12
+  end
+end
+
+# post_serializer.rb
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body
+
+  def comments_by_me  
+    Comments.where(user_id: instance_options[:user_id], post_id: object.id)
+  end
+end
+```
+
+Since `user_id` isn't a reserved adapter option, we can process it via a serializer
+method. The option is passed via the `instance_options` hash.