From aa2fb685d95959ce32ae63e1ea7587fcffdcec51 Mon Sep 17 00:00:00 2001
From: Ben Balter <ben.balter@github.com>
Date: Thu, 3 Apr 2014 13:57:40 -0400
Subject: [PATCH] I am the King of Copy

---
 site/docs/collections.md | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/site/docs/collections.md b/site/docs/collections.md
index 0016cf4c..f4c2239e 100644
--- a/site/docs/collections.md
+++ b/site/docs/collections.md
@@ -14,14 +14,23 @@ permalink: /docs/collections/
   </p>
 </div>
 
+<div class="note warning">
+  <h5>Collections support is unstable and may change</h5>
+  <p>
+    This is an experimental feature and that the API may likely change until the feature stabilizes.
+  </p>
+</div>
+
 Put some things in a folder and add the folder to your config. It's simple...
 
-Why did we write this feature? What is it useful for?
+Not everything is a post or a page. Maybe you want to document the various methods in your open source project, members of a team, or talks at a conference. Collections allow you to define a new type of document that behave like Pages or Posts do normally, but also have their own unique properties and namespace.
 
 ## Using Collections
 
 ### Step 1: Tell Jekyll to read in your collection
 
+Add the following to your site's `_config.yml` file, replacing `my_collection` with the name of your collection:
+
 {% highlight yaml %}
 collections:
 - my_collection
@@ -30,12 +39,13 @@ collections:
 ### Step 2: Add your content
 
 Create a corresponding folder (e.g. `<source>/_my_collection`) and add documents.
-YAML front-matter is read in as data if it exists, if not, then everything is just
-stuck in the Document's `content` attribute.
+YAML front-matter is read in as data if it exists, if not, then everything is just stuck in the Document's `content` attribute.
+
+Note: the folder must be named identical to the collection you defined in you config.yml file, with the addition of the preceding `_` character.
 
 ### Step 3: Optionally render your collection's documents into independent files
 
-If you'd like your files rendered, add it to your config:
+If you'd like Jekyll to create a public-facing, rendered version of each document in your collection, add your collection name to the `render` config key in your `_config.yml`:
 
 {% highlight yaml %}
 render: