README.md in localjob-0.0.1 vs README.md in localjob-0.0.2

@@ -10,22 +10,22 @@
 simple that does not rely on any external services. A bigger goal with the
 project is to be able to migrate to another background queue system by switching
 adapter: `Localjob.adapter = Resque` to switch to Resque, without changes to
 your own code.
 
-The POSIX message queue is persistent till reboot. You will need to tune system
-parameters for your application, please consult [posix-mqueue][pmq-gem]'s
+The POSIX message queue is persistent till reboot. You **will need to tune system
+parameters for your application**, please consult [posix-mqueue][pmq-gem]'s
 documentation.
 
-Localjob works on Ruby >= 2.0.0 and Linux.
+Localjob works on Ruby >= 2.0.0. On Linux, it will use the POSIX message queue.
+On OS X (and Windows, not tested) it will use a mock class instead of the
+message queue, to aid you in testing and running Localjob in development.
 
-WIP not everything works as advertised, but try it out and report anything that
-doesn't work! It's not released as a gem yet, so add the following to your
-Gemfile to use it:
+Add it to your Gemfile:
 
 ```ruby
-gem 'localjob', git: "[e-mail]:Sirupsen/localjob.git"
+gem 'localjob'
 ```
 
 ## Usage
 
 Localjobs have the following format:
@@ -47,11 +47,91 @@
 ```ruby
 queue = Localjob.new
 queue << EmailJob.new(current_user.id, welcome_email)
 ```
 
-Then spawn a worker with `localjob work`. It takes a few arguments, like `-d` to
-deamonize itself. `localjob help work` to list all options.
+A job is serialized with YAML and pushed onto a persistent POSIX message queue.
+This means a worker does not have to listen on the queue to push things to it.
+Workers will pop off the message queue, but only one will receive the job.
+Deserialize the message to create an instance of your object, and call
+`#perform` on the object.
+
+### Rails initializer
+
+For easy access to your queues in Rails, you can add an initializer to set up a
+constant referencing each of your queues. This allows easy access anywhere in
+your app. In `config/initializers/localjob.rb`:
+
+```ruby
+BackgroundQueue = Localjob.new("main-queue")
+```
+
+Then in your app you can simply reference the constant to push to the queue:
+
+```ruby
+BackgroundQueue << EmailJob.new(current_user.id, welcome_email)
+```
+
+### Managing workers
+
+Spawning workers can be done with `localjob`. Run `localjob work` to spawn a
+single worker. It takes a few arguments. The most important being `--require`
+which takes a path the worker will require before processing jobs. For Rails,
+you can run `localjob work` without any arguments. `localjob(2)` has a few other
+commands such as `list` to list all queues and `size` to list the size of all
+queues. `localjob help` to list all commands.
+
+Gracefully shut down workers by sending `SIGQUIT` to them. This will make sure
+the worker completes its current job before shutting down. Jobs can be sent to
+the queue meanwhile, and the worker will process them once it starts again.
+
+### Queues
+
+Localjobs supports multiple queues, and workers can be assigned to queues. By
+default everything is on a single queue. To push to a named queue:
+
+```ruby
+email = Localjob.new("email")
+email << EmailJob.new(current_user.id, welcome_email)
+```
+
+The worker spawn command `localjob work` takes a `--queues` argument which is a
+comma seperated list of queues to listen on, e.g. `localjob work --queues email,webhooks`.
+
+### Testing
+
+Create your instance of the queue as normal in your setup:
+
+```ruby
+def setup
+  @queue = LocalJob.new("test-queue")
+end
+```
+
+In your `teardown` you'll want to destroy your queue:
+
+```ruby
+def teardown
+  @queue.destroy
+end
+```
+
+You can get the size of your queue by calling `@queue.size`. You pop off the
+queue with `@queue.shift`. Other than that, just use the normal API. You can
+also read the tests for Localjob to get an idea of how to test. Sample test:
+
+```ruby
+def test_pop_and_send_to_worker
+  WalrusJob.any_instance.expects(:perform)
+
+  @localjob << WalrusJob.new("move")
+
+  job = @localjob.shift
+  @worker.process(job)
+
+  assert_equal 0, @localjob.size
+end
+```
 
 [pmq]: http://linux.die.net/man/7/mq_overview
 [pmq-gem]: https://github.com/Sirupsen/posix-mqueue
 [blog]: http://sirupsen.com/unix-background-queue/