Update PR based on comments

Author: Yohan Robert

CHANGELOG.md

@@ -31,6 +31,8 @@ Fixes:
 - [#1881](https://github.com/rails-api/active_model_serializers/pull/1881) ActiveModelSerializers::Model correctly works with string keys (@yevhene)
 
 Misc:
+
+- [#1981](https://github.com/rails-api/active_model_serializers/pull/1981) Improve link and pagination documentation(@groyoh)
 - [#1767](https://github.com/rails-api/active_model_serializers/pull/1767) Replace raising/rescuing `CollectionSerializer::NoSerializerError`,
   throw/catch `:no_serializer`. (@bf4)
 - [#1839](https://github.com/rails-api/active_model_serializers/pull/1839) `fields` tests demonstrating usage for both attributes and relationships. (@NullVoxPopuli)

docs/howto/add_link.md

@@ -4,6 +4,20 @@
 
 `ActiveModelSerializers` offers you many ways to add links in your JSON reponse depending on the adapter you are using.
 
+Note that within the following examples, we set the `adapter` option, but that is not needed if the `ActiveModelSerializers.config.adapter` variable is properly set. Also, some examples are given for both Rails and [non-Rails usage](outside_controller_use.md).
+
+Unless stated otherwise, the examples given here will assume that the following classes are defined:
+
+```ruby
+class User < ActiveModelSerializers::Model
+  attributes :id, :name
+end
+
+class UserSerializer < ActiveModel::Serializer
+  attributes :id, :name
+end
+```
+
 ## JSON API adapter
 
 The JSON API specification allows the usage of the `links` member for representing links in three cases:
@@ -18,19 +32,9 @@ The JSON API specification allows the usage of the `links` member for representi
 In order to provide top-level links, you will need to specify the `links` option to the serialization:
 
 ```ruby
-class UserSerializer < ActiveModel::Serializer
-  attributes :id, :name
-end
-
 user = User.new(id: 1, name: "John")
-links = {
-  home: "https://www.example.com/"
-}
-resource = ActiveModelSerializers::SerializableResource.new(
-  user,
-  adapter: :json_api,
-  links: links
-)
+links = { home: "https://www.example.com/" }
+resource = ActiveModelSerializers::SerializableResource.new(user, adapter: :json_api, links: links)
 resource.to_json
 ```
 
@@ -57,18 +61,16 @@ When using Rails, you can add top-level links by providing the `links` option to
 class UserController < ActionController::Base
   def show
     user = User.new(id: 1, name: "John")
-    links = {
-      home: "https://www.example.com/"
-    }
+    links = { home: "https://www.example.com/" }
     render json: user, adapter: :json_api, links: links
   end
 end
 ```
 
 #### Pagination
 
-`ActiveModelSerializers` will provides automatic pagination links for collections if use [Kaminari](https://github.com/amatsuda/kaminari)
-or [WillPaginate](https://github.com/mislav/will_paginate):
+`ActiveModelSerializers` will provide automatic pagination links for collections if you use [Kaminari](https://github.com/amatsuda/kaminari)
+or [WillPaginate](https://github.com/mislav/will_paginate) and the `ActiveModelSerializers.config.jsonapi_pagination_links_enabled` config is set to `true` (defaults to `true`). To disable this feature, you can simply set this config to `false`.
 
 ```ruby
 class UserController < ActionController::Base
@@ -108,15 +110,15 @@ Any of these actions would result in:
 }
 ```
 
-Note that `ActiveModelSerializers` pagination relies on a collection that has the methods `current_page`, `total_pages`, and `size`, such as are supported by both [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate). If you want to have paginated links your collections but don't want to use neither Kaminari nor WillPaginate, make sure to define these methods.
+Note that it is possible to opt-out `ActiveModelSerializers` pagination relies on a collection that has the methods `current_page`, `total_pages`, and `size`, such as are supported by both [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate). If you want to have paginated links your collections but don't want to use neither Kaminari nor WillPaginate, make sure to define these methods.
 
 ### [Resource link](http://jsonapi.org/format/#document-resource-object-links)
 
 You can use the `link` class method to define the links you need in the resource's primary data:
 
 ```ruby
 class UserSerializer < ActiveModel::Serializer
-  attributes :id, :name
+  attributes :name
 
   link(:self) { user_path(object.id) }
   link(:posts) { posts_path(user_id: object.id) }
@@ -190,7 +192,7 @@ If you only want the `links` member to appear you can set `include_data false` w
 
 ```ruby
 class UserSerializer < ActiveModel::Serializer
-  attributes :id, :name
+  attributes :name
   has_many :posts do
     link(:self) do
       include_data false
@@ -232,9 +234,6 @@ The `json` is not able to handle links defined by the `link` class method. Howev
 ### Via `meta`
 
 ```ruby
-class UserSerializer < ActiveModel::Serializer
-  attributes :id, :name
-end
 user = User.new(id: 1, name: "John")
 meta = {
   links: {

docs/howto/handle_pagination.md

@@ -18,7 +18,7 @@ resource = ActiveModelSerializers::SerializableResource.new(users, adapter: :jso
 resource.to_json
 ```
 
-* For usage of top-level links see [add_links.md#pagination].
+* For usage of top-level links [check here](add_links.md#pagination).
 
 ## JSON adapter