diff --git a/README b/README
index 1838e4329..ab39ba3fe 100644
--- a/README
+++ b/README
@@ -1,13 +1,15 @@
 jam-db
 ======
 
-Schema migrations for the jam-db database
+Schema migrations for the jam-db database.  Uses the [pg_migrate tool](https://github.com/sethcall/pg_migrate) tool.  The github page of pg_migrate also has some documentation and rationale behind this approach of migrations.
 
 Overview
 --------
-jam-db defines the migrations that comprise the jam-db database.
+jam-db defines the migrations that comprise the jam-db database.  It uses pg_migrate to package up the migrations iinto a gem or (TODO) jar. You can then use those packaged up versions of the schemas in downstream projects.
 
-Environment
+The main reason the 'pg_migrate' approach is taken is to make to possible to use the database like an interface, freed from any one project or language.
+
+Environmenti
 -----------
 * [rvm](https://rvm.io/) with ruby 1.9.3 installed and activated.  rvm needs to be activated in your shell (the installation process does this)
 * bash . If on windows, use git bash or cygwin. Bash is used as the build script technology.  (could change very easily)
@@ -15,8 +17,9 @@ Environment
 
 Building
 --------
-# one-time: ff you just installed rvm, cd into this project's base directory.  rvm will ask you to trust the .rvmrc.  Do so.
-# type ./build
+# one-time: if you just installed rvm, cd into this project's base directory.  rvm will ask you to trust the .rvmrc.  Do so.
+# type:
+ ./build # this will clean your 'target' directory, and rebuild from scratch. It takes seconds.
 
 Using
 -----
@@ -27,9 +30,18 @@ https 'https://rubygems.org'
 
 gem 'jam_db', :path => '~/workspace/jam-db/target/ruby_package'
 `
-
-
-
+Then, to cause a migration, do something like:
+
+# make sure you have the jam_db gem
+bundle install
+
+# migrate the database (assumes you've created the 'jam' database already).
+bundle exec jam_db --connopts="dbname:jam host:localhost user:postgres password:postgres" --verbose
+
+# you can see if it worked by typing:
+
+psql jam
+> select * from pgmigrate.pg_migrate;