README.md in flirt-0.1.1 vs README.md in flirt-0.2.0

@@ -166,16 +166,65 @@
 
 ### Flirt is opinionated
 
 There is no set-up beyond requiring the gem.
 
-Events are only allowed to be represented as symbols. Using strings or other objects will result in an exception, helping to spot and squash certain kinds of bugs early.
+Events are canonly be represented as symbols, helping to spot and squash certain kinds of bugs early.
 
 Only one object - Flirt - can be listened to, reducing the danger of implicit coupling between publishers and subscribers. Subscribers listen to events, not objects.
 
+### Flirt doesn't use threads or persistence frameworks. 
+
+This means events are fired in a deterministic way, without over-obfuscating the control flow for debug tools. You can depend on listeners being called before, for example, the end of a controler call. If you wish to delegate a task to a worker task (like Sidekiq for example) it's easy enough to do in a listener.
+
 ### Flirt has a great name
 
 Seriously, why use any other gem when you could be flirting instead?
+
+## Antipatterns amd misuse
+
+#### Clearing and disabling
+
+The ```clear```, ```enable``` and ```disable``` features are provided to aid testing. If you find yourself reaching for them in production code you're probably using the wrong pattern, or you may need to re-think your architecture.
+
+Have a look at decorators if you need to add different functionality to a model depending on where it's called.
+
+Alternatively, change the location in the code where you publish your events. A useful move in Rails is from the model to the controller, to avoid admin or other background updates triggering events that should only be based on user actions. This move can also help break some event loops, where a side effect of one event causes another event to fire and vice versa.
+
+#### Garbage collection
+
+If you find yourself creating and throwing away multiple listener objects, Ruby will still keep references to those objects for the lifetime of the application.  This can result in memory leaks, as Ruby will not be able to garbage collect the listeners. To avoid this situation, ensure you unsubscribe from any events when you're done with them. Alternatively, on subscription you can request that Flirt uses weak references:
+
+```ruby
+Flirt.subscribe object, :flipped, with: :flipped_callback, weakref: true 
+```
+
+This means that garbage collection can target the listener. Be careful though, as the listener will be garbage collected unless you keep a reference to it somewhere else. This kind of code would be problematic:
+
+```ruby
+def set_listener
+  Flirt.subscribe TossedListener.new, :tossed, with: :tossed_callback, weakref: true
+end
+```
+
+This will lead to intermittent bugs as nothing keeps a reference to ```TossedListener.new```. The listener will work until garbage collection kicks in.
+
+Flirt defaults to using strong references to ensure consistent behaviour.
+
+## Set-up
+
+While no set-up is required for Flirt use, there is a quirk of Rails autoloading that could cause issues.
+
+If you wish to use listeners on a class level, you must make sure the class is loaded. If the class definition has not been required, the listener will not be registered.
+
+Rails auto-loads classes when they're first referenced so unless you take an extra step, class-level listeners won't ever be loaded.
+
+Placing the following code in an initializer will ensure that anything you place in the ```#{Rails.root}/app/listeners``` directory will get loaded when the Rails framework boots up:
+
+```ruby
+# /config/initializers/flirt.rb
+Dir["#{Rails.root}/app/listeners/**/*.rb"].each {|file| require file }
+```
 
 ##Testing
 
 In order to test units of behaviour, you probably want to disable Flirt and test each unit of your code in isolation. You can always enable Flirt or individual events in your test file for integration tests.