Update README

Tweaks:
 * Add more detail to how the gem works in the summary section
 * Set `increment_by` value to what we're using as the default
 * Disclaimer that `increment_by` doesn't do anything, the configuration
 must be done on the MySQL server itself.
 * Updated outdated testing steps
 * Moved the testing section to the bottom, it was in the middle of the
 installation and configuration instructions

README.md

@@ -4,15 +4,13 @@
 
 ## Summary
 
-This plugin does a lot of the heavy lifting needed to have an external MySQL based global id generator as described in this article from Flickr
+This gem allows you to generate global IDs as described in [this article from Flickr](http://code.flickr.com/blog/2010/02/08/ticket-servers-distributed-unique-primary-keys-on-the-cheap/) for your Ruby on Rails applications. It does this by patching
+`ActiveRecord::Base` and `ActiveRecord::Migration` so that new models retrieve their ID from one of the configured
+alloc servers (short for ID allocation databases), this functionality is opt-out, not opt-in. The databases responsible
+for allocating your identifiers (aka id_servers) should have their `auto_increment_increment` and `auto_increment_offset`
+setting [configured globally](https://dev.mysql.com/doc/refman/5.6/en/replication-options-master.html#sysvar_auto_increment_increment).
 
-(http://code.flickr.com/blog/2010/02/08/ticket-servers-distributed-unique-primary-keys-on-the-cheap/)
-
-There are three parts to it: configuration, migration and object creation
-
-### Interactions with other databases
-
-This gem only supports MySQL. Theoretically it should be easy to port it to other DBs, we just don't need to.
+This gem only supports MySQL databases and the documentation is written with that in mind but the concept could be applied to others.
 
 ## Installation
 
@@ -43,10 +41,12 @@ Then setup these servers, and other defaults in your environment.rb:
 ```rb
 GlobalUid::Base.global_uid_options = {
   id_servers: [ 'id_server_1', 'id_server_2' ],
-  increment_by: 3
+  increment_by: 5
 }
 ```
 
+The `increment_by` value configured here does not dictate the value on your alloc server and must remain in sync with the value of [`auto_increment_increment`](https://dev.mysql.com/doc/refman/5.6/en/replication-options-master.html#sysvar_auto_increment_increment)
+
 Here's a complete list of the options you can use:
 
 | Name                  | Default                                    | Description                                                                                                |
@@ -56,24 +56,15 @@ Here's a complete list of the options you can use:
 | `:query_timeout`      | 10 seconds                                 | Timeout for retrieving a global UID from a server before we move on to the next server                     |
 | `:connection_retry`   | 10 minutes                                 | After failing to connect or query a UID server, how long before we retry                                   |
 | `:notifier`           | A proc calling `ActiveRecord::Base.logger` | This proc is called with two parameters upon UID server failure -- an exception and a message              |
-| `:increment_by`       | 5                                          | Chooses the step size for the increment.  This will define the maximum number of UID servers you can have. |
-
-### Testing
-
-```
-mysqladmin -uroot create global_uid_test
-mysqladmin -uroot create global_uid_test_id_server_1
-mysqladmin -uroot create global_uid_test_id_server_2
-```
-
-Copy test/config/database.yml.example to test/config/database.yml and make the modifications you need to point it to 2 local MySQL databases. Then +rake test+
+| `:increment_by`       | 5                                          | Used to validate number of ID servers, preventing connections if there are more servers than the given increment |
 
 ### Migration
 
 Migrations will now add global_uid tables for you by default.  They will also change
 your primary keys from signature "PRIMARY KEY AUTO_INCREMENT NOT NULL" to "PRIMARY KEY NOT NULL".
 
-If you'd like to disable this behavior, you can write:
+If you'd like to disable this behavior, you can by setting `use_global_uid` to `false` as show
+below:
 
 ```rb
 class CreateFoos < ActiveRecord::Migration
@@ -117,4 +108,10 @@ If you're using a non standard uid table then pass that in.
 generate_uid(uid_table: '<name>')
 ```
 
+### Testing
+
+This gem uses `minitest` and the test suite can be run with `bundle exec rake test`.
+
+If you want to run a particular scenario, it can be done by passing the line number in, e.g. `bundle exec ruby test/global_uid_test.rb -l 18`
+
 Copyright (c) 2010 Zendesk, released under the MIT license