diff --git a/guides/README.md b/guides/README.md
index a71fcaabd4f..b1975daaffe 100644
--- a/guides/README.md
+++ b/guides/README.md
@@ -1,4 +1,15 @@
-Based on [https://github.com/joshukraine/middleman-gulp](https://github.com/joshukraine/middleman-gulp)
+# Solidus Guides
+
+If you want to contribute to the Solidus documentation be sure to read the
+[dedicated section](https://github.com/solidusio/solidus/blob/master/guides/source/contributing.html.md) first.
+
+The documentation files can be found
+[inside the `source/` folder](https://github.com/solidusio/solidus/tree/master/guides/source).
+
+---
+
+The Solidus documentation is published with [Middleman](https://middlemanapp.com),
+and based on [https://github.com/joshukraine/middleman-gulp](https://github.com/joshukraine/middleman-gulp).
 
 Requirements
 ------------
@@ -13,7 +24,7 @@ Usage
 
 1. Install ruby gems `bundle install`
 
-2. Install npm packages `npm install` 
+2. Install npm packages `npm install`
 
 3. Start the Middleman server. Note that this will also invoke Webpack via the external pipeline.
 
@@ -26,4 +37,5 @@ $ bundle exec middleman server
 ```bash
 $ bundle exec middleman build
 ```
+
 5. Set proper `base_url` in config.rb
diff --git a/guides/source/contributing.html.md b/guides/source/contributing.html.md
index 91b267f94e2..dd08b61172a 100644
--- a/guides/source/contributing.html.md
+++ b/guides/source/contributing.html.md
@@ -2,6 +2,9 @@
 
 We hope that you will consider contributing to the Solidus documentation.
 
+The Solidus documentation sources are hosted in the main repository
+[inside the `guides/` folder](https://github.com/solidusio/solidus/tree/master/guides#readme).
+
 We want to provide the Solidus community with consistent, easy-to-read, and
 easy-to-maintain articles. If you decide to submit a pull request, please try to
 follow the guidelines listed here.
diff --git a/guides/source/developers/extensions/decorators.html.md b/guides/source/developers/extensions/decorators.html.md
index fda8b864952..0429d1ddca6 100644
--- a/guides/source/developers/extensions/decorators.html.md
+++ b/guides/source/developers/extensions/decorators.html.md
@@ -13,15 +13,13 @@ For example, if you want to add a method to the `Spree::Order` model, you could
 create `/app/models/mystore/order_decorator.rb` with the following contents:
 
 ```ruby
-module MyStore
-  module OrderDecorator
-    def total
-      super + BigDecimal(10.0)
-    end
+module MyStore::OrderDecorator
+  def total
+    super + BigDecimal(10.0)
   end
-end
 
-Spree::Order.prepend MyStore::OrderDecorator
+  Spree::Order.prepend self
+end
 ```
 
 This creates a new module called `MyStore::OrderDecorator` that prepends its