Tweaked the SPECS document and added a rough outline for the new spec…

… organization

SPECS

@@ -16,7 +16,7 @@ Writing Specs
   * Use existing models that are part of a metaphor.
   * Nest describe blocks (2 or 3 levels deep is probably fine).
   * Limit a describe block to 10 - 15 examples.
-  * Group specs by method being tested.
+  * Group specs by method being tested. (See the 'Ordering Specs' section)
   * Use custom matchers.
 
   = DON'T:
@@ -50,4 +50,14 @@ Mocks and Stubs
 
   Obviously, mocks and stubs are a powerful feature when it comes to BDD;
   however, remember that you are writing specs for behavior and NOT
-  implementation.
+  implementation.
+
+Ordering Specs
+==============
+
+  Specs aren't much use if nobody can find where anything is, so keeping specs
+  well organized is critical. Currently, we are trying out the following
+  structure:
+
+    * List guidelines here...
+

spec/integration/resource_spec.rb

@@ -1,5 +1,10 @@
 require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper'))
 
+# ------------------------------------------------------------
+# -----   Read SPECS for information about how to read   -----
+# -----   and contribute to the DataMapper specs.        -----
+# ------------------------------------------------------------
+
 if ADAPTER
   describe "DataMapper::Resource with #{ADAPTER}" do
 
@@ -15,8 +20,6 @@
     it "should be able to destroy objects" do
       lambda { @zoo.destroy.should be_true }.should_not raise_error
     end
-
-  # --------------- ATTRIBUTE METHODS ---------------
 
     describe '#attribute_get' do
       it 'should provide #attribute_get' do
@@ -45,14 +48,6 @@
       end
     end
 
-    describe '#id' do
-      it "should be awesome"
-    end
-
-    describe '#key' do
-      it "should be awesome"
-    end
-
     describe '#eql?' do
       it "should return true if the objects are the same instances"
       it "should return false if the other object is not an instance of the same model"
@@ -62,7 +57,21 @@
       it "should return false if any of the properties are different"
     end
 
-  # --------------- REPOSITORY WRITE METHODS ---------------
+    describe '#id' do
+      it "should be awesome"
+    end
+
+    describe '#inspect' do
+      it "should return a string representing the object"
+    end
+
+    describe '#key' do
+      it "should be awesome"
+    end
+
+    describe '#pretty_print' do
+      it "should display a pretty version of inspect"
+    end
 
     describe '#save' do
 
@@ -78,23 +87,10 @@
 
     end
 
-  # --------------- REPOSITORY METHODS ---------------
-
     describe '#repository' do
       it "should return the repository associated with the object if there is one"
       it "should return the repository associated with the model if the object doesn't have one"
     end
-
-  # -------------- MISCELLANEOUS METHODS ---------------
-
-    describe '#inspect' do
-      it "should return a string representing the object"
-    end
-
-    describe '#pretty_print' do
-      it "should display a pretty version of inspect"
-    end
-
   end
 end