several updates to docs

please review f226383 as it was causing silent discards of on_behalf_of parameters using balanced-ruby-0.6.0