almost finished with the readme. At what point do we begin splitting them into chapters

diff --git a/README.rdoc b/README.rdoc
index 5c76dc1..43c6855 100644 (file)
--- a/README.rdoc
+++ b/README.rdoc
@@ -28,23 +28,82 @@ can be done in two ways
 
 *nix platforms, from the koans directory
 
-    [koans] $ rake                              # runs the default target :walk_the_path
-    [koans] $ ruby path_to_enlightenment.rb     # simply call the file directly
+    [ruby_koans] $ rake                           # runs the default target :walk_the_path
+    [ruby_koans] $ ruby path_to_enlightenment.rb  # simply call the file directly
     
 Windows is the same thing
 
-    c:\dev\koans\rake                           # runs the default target :walk_the_path
-    c:\dev\koans\ruby path_to_enlightenment.rb  # simply call the file directly
+    c:\ruby_koans\rake                             # runs the default target :walk_the_path
+    c:\ruby_koans\ruby path_to_enlightenment.rb    # simply call the file directly
     
+=== Red, Green, Refactor
+
+In test-driven development the mantra has always been, red, green, refactor.  Write a
+failing test and run it (red), make the test pass (green), then refactor it (that is
+look at the code and see if you can make it any better.  In this case you will need
+to run the koan and see it fail (refactor), make the test pass (green), then take a 
+moment and reflect upon the test to see what it is teaching you.  
+
+The very first time you run it you will see the following output:
+
+    [ ruby_koans ] $ rake
+    (in /Users/person/dev/ruby_koans)
+    cd koans
+    
+    Thinking AboutAsserts
+      test_assert_truth has damaged your karma.
+    
+    You have not yet reached enlightenment ...
+    <false> is not true.
+    
+    Please meditate on the following code:
+    ./about_basics.rb:10:in `test_assert_truth'
+    path_to_enlightenment.rb:27
+
+    mountains are merely mountains
+    
+You have come to your first stage. If you notice it is telling you where to look for
+the first solution:
+
+    Please meditate on the following code:
+    ./about_basics.rb:10:in `test_assert_truth'
+    path_to_enlightenment.rb:27
+    
+We then open up the about_basics.rb file and look at the first test:
+
+    # We shall contemplate truth by testing reality, via asserts.
+    def test_assert_truth
+      assert false                # This should be true
+    end
+
+We then change the +false+ to +true+ and run the test again.  After you are
+done, think about what you are learning.  In this case, ignore everything except
+the method name (+test_assert_truth+) and the parts inside the method (everything 
+before the +end+).  
+ 
+In this case the goal is for you to see that if you pass a value to the +assert+ 
+method, it will either ensure it is +true+ and continue on, or fail if in fact
+the statement is +false+.   
+ 
 == Inspiration
 
 A special thanks to Mike Clark and Ara Howard for inspiring this project.  Mike Clark
-wrote an excellent blog post in March of '05 about learning Ruby through unit 
-testing [1]. This sparked an idea that has taken a bit to solidify, that of bringing
-new rubyists into the community through testing. 
+wrote an excellent blog post about learning Ruby through unit testing. This sparked 
+an idea that has taken a bit to solidify, that of bringing new rubyists into the 
+community through testing. Ara Howard then gave us the idea for the Koans in his 
+ruby quiz entry an Meta Koans (a must for any rubyist wanting to improve their skills).
+
+Mike Clark's post ::  http://www.clarkware.com/cgi/blosxom/2005/03/18
+Meta Koans        ::  http://rubyquiz.com/quiz67.html
+
+== Other Resources
+
+The Ruby Language               ::  http://ruby-lang.org
+
+Dave Thomas' introduction to Ruby
+Programming Ruby (the Pick Axe) ::  http://pragprog.com/titles/ruby/programming-ruby
 
-Ara Howard then gave us the idea for the Koans in his ruby quiz entry an Meta Koans
-(a must for any rubyist wanting to improve their skills).
+Brian Marick's fantastic guide for beginners
+Everyday Scripting with Ruby    ::  http://pragprog.com/titles/bmsft/everyday-scripting-with-ruby
 
-[1] http://www.clarkware.com/cgi/blosxom/2005/03/18
-[2] http://rubyquiz.com/quiz67.html
+Try Ruby in your browser        ::  http://tryruby.hobix.com/
\ No newline at end of file

diff --git a/Rakefile b/Rakefile
index 4c2e1c7..0c07899 100644 (file)
--- a/Rakefile
+++ b/Rakefile
@@ -1,7 +1,14 @@
+require 'rubygems'
+require 'rake/rdoctask'
 
 task :default => :walk_the_path
 
 task :walk_the_path do
   cd 'koans'
   ruby 'path_to_enlightenment.rb'
-end
\ No newline at end of file
+end
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc", "koans/*.rb")
+end