update 11-decorators.md

docs/11-decorators.md

@@ -1,66 +1,53 @@
 # Decorators
 
-Active Admin supports the use of decorators for resources. Resources will be
-decorated for the index and show blocks. The
-[draper](https://github.com/drapergem/draper) gem is recommended but not required
-(more on requirements below). Note, that Active Admin works out of the box with
-Draper `>= 1.0.0`.
-
-## Configuration
-
-    ActiveAdmin.register Post do
-      decorate_with PostDecorator
-    end
-
-## Example Usage
-
-This example uses [draper](https://github.com/drapergem/draper).
-
-    # Gemfile
-    gem 'draper', '>= 1.0.0'
-
-Assuming a post and a post decorator
-
-    class Post < ActiveRecord::Base; end
-
-    class PostDecorator < ApplicationDecorator
-      decorates :post
-
-      def image
-        h.image_tag model.image_url
-      end
-    end
-
-Then the following is possible
-
-    ActiveAdmin.register Post do
-      decorate_with PostDecorator
-
-      index do
-        column(:title)
-        column(:image)
-      end
-
-      show do
-        attributes_table do
-          row(:title)
-          row(:image)
-        end
-      end
-    end
+Active Admin allows you to use the decorator pattern to provide view-specific
+versions of a resource. [Draper](https://github.com/drapergem/draper) is
+recommended but not required.
+
+## Example usage
+
+```ruby
+# app/models/post.rb
+class Post < ActiveRecord::Base
+  # has title, content, and image_url
+end
+
+# app/decorators/post_decorator.rb
+class PostDecorator < ApplicationDecorator
+  delegate_all
+
+  def image
+    h.image_tag model.image_url
+  end
+end
+
+# app/admin/post.rb
+ActiveAdmin.register Post do
+  decorate_with PostDecorator
+
+  index do
+    column :title
+    column :image
+    actions
+  end
+end
+```
 
 ## Forms
 
-Note that the resource proveded to form_for also gets decorated.
-
-In most cases this will work as expected. However, it is possible to disable
-automatic decoration in the form with the `decorate` option:
+If you decorate an AA resource, the form will also be docrated.
 
-    ActiveAdmin.register Post do
-      decorate_with PostDecorator
+In most cases this will work as expected, but if your decorator uses the same
+method name as an attribute and it returns a modified version of the attribute's
+value, you'll want to set `decorate: false` to make sure that the population of
+existing values happens correctly:
 
-      form decorate: false do
-        # ...
-      end
-    end
+```ruby
+ActiveAdmin.register Post do
+  decorate_with PostDecorator
 
+  form decorate: false do
+    # ...
+  end
+end
+```