trailguide 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac4411fe00b16770b749c3ec2005e0d10f37cc05c2549d6fb8ff9613d31c7ba9
-  data.tar.gz: 29af693f9ddb1855b60c627947067994834d05661580d793994637c9f92fb3af
+  metadata.gz: a1f31e734d2b0165ffe08887a4e7a21cceebe8c6aba8c4ff72d9393f1fd6095a
+  data.tar.gz: ea8cd225a315add5f4512f8bc38bd28bc372741c45185eb4c987069165c3ad4b
 SHA512:
-  metadata.gz: 1f2418947bc8283761b0283fd485182abc8c1b6df44d9de7ae65e227286352065788c85262f31ab0e70cc70517310d278b858bf8ddea02d9af3ce12a02e87950
-  data.tar.gz: 76d8edbad6605be76f323ec104fc80a180f72a86e4d86e3e0703bc8734145c8140bad2a6345667175c9fbb8e70a5b0bc5ad35713361761ba3dc434818743403d
+  metadata.gz: ccb5f9cd9e367481380b8afbc6a763149967bd59f0bbe6d7f0c0693d90ccae7d0b6a16bf9e2544ef4362504cb417cb327f44001a044d8bbc4e318a1377b6ac45
+  data.tar.gz: 19b6761660d76db06b36114496fd9f835d08fdf70e99a7e117369d800175a79f18e21c6436f7f37a84529e3370bdae2f8285a49e25ae00182cc05f801c8daea9

data/README.md

@@ -1,16 +1,32 @@
 # TrailGuide
 
-TrailGuide is a rails engine providing a framework for running user experiments and A/B tests in rails apps.
+[![Build Status](https://travis-ci.org/markrebec/trailguide.svg?branch=master)](https://travis-ci.org/markrebec/trailguide)
+[![Coverage Status](https://coveralls.io/repos/github/markrebec/trailguide/badge.svg?branch=master)](https://coveralls.io/github/markrebec/trailguide?branch=master)
+
+TrailGuide is a framework to enable running A/B tests, user experiments and content experiments in rails applications. It is backed by redis making it extremely fast, and provides configuration options allowing for flexible, robust experiments and behavior.
+
+**NOTE**: I'm currently working towards an official release, refactoring a few things and filling in additional spec coverage and documentation. The current release is stable, however there may be slight changes to the API and usage between now and 1.0.0. In the meantime any feedback, issues or pull requests are welcome!
+
+## Features
+
+* **Fast** - TrailGuide makes efficient use of redis, storing a few simple metadata key/value pairs for experiments. Combined with ruby class-based experiments, efficient built-in algorithms, and participant adapters, enrolling in an experiment takes only a few milliseconds.
+* **Flexible** - Core behavior, participant assignment and individual experiments are highly configurable and can be used in almost any context, with options to control everything from variant options and metrics, to enrollment, conversion behavior, request filtering and more.
+* **Hooks and Callbacks** - There are a number of hooks available to handle things like failover cases or filtering participation/conversion, as well as callbacks to enable logging/tracking/whatever when lifecycle or enrollment events occur. (TODO wiki link to callbacks page)
+* **Algorithms** - TrailGuide comes with a few built-in algorithms for common use cases, or you can create your own algorithm class by following a simple interface. (TODO wiki link to algorithm page)
+* **Conversion Goals** - Define simple conversion goals or more complex funnels, and track how your variants are performing against those goals.
+* **Experiment Groups** - If you're running a large number of experiments, it can be helpful to organize them into logical groups, which can also be referenced when converting multiple experiments against shared conversion goals.
+* **Combined Experiments** - Combined experiments are a way to share configuration (variants, goals, groups, flags, etc.), lifecycle (running, paused, etc.) and participation between two or more experiments, while tracking conversion and managing winning variants individually.
+* **Analysis** - Once your experiment is complete TrailGuide can provide you with results using the built-in analyzers, either z-score (default) or bayesian. (TODO wiki link to analysis)
 
 ## Getting Started
 
 ### Requirements
 
-Currently only rails 5.x is officially tested/supported, and trailguide requires redis to store experiment metadata and (optionally) participants.
+Currently only rails 5.x is officially tested/supported, and TrailGuide requires redis to store experiment metadata and (optionally) participants' assignment.
 
-`docker-compose` is a great way to run redis in development. Take a look at the `docker-compose.yml` in the root of this repo for an example.
+`docker-compose` is a great way to run redis in development. Take a look at the [`docker-compose.yml` in the root of this repo](https://github.com/markrebec/trailguide/blob/master/docker-compose.yml) for an example.
 
-In production I recommend configuring redis as a persistent datastore (rather than a cache), in order to avoid evicting experiment or participant keys unexpectedly.
+In production I recommend configuring redis as a persistent datastore (rather than a cache), in order to avoid evicting experiment or participant keys unexpectedly. You can [read more about key eviction and policies here](https://redis.io/topics/lru-cache).
 
 ### Installation
 
@@ -22,38 +38,25 @@ gem 'trailguide'
 
 Then run `bundle install`.
 
-### Engine & Admin Routes
+### Configuration
 
-If you plan on using the included javascript client, or if you just want an API to interact with experiments in other ways, you can mount the engine in your route config:
+By default the redis client will attempt to connect to redis on `localhost:6379`, which is usually fine for development/testing but won't work in other environments.
 
-```ruby
-# /config/routes.rb
+Configure redis by either setting a `REDIS_URL` environment variable:
 
-Rails.application.routes.draw do
-  # ...
-
-  mount TrailGuide::Engine => 'api/experiments'
-
-  # ...
-end
+```
+REDIS_URL=redis://127.0.0.1:6379
 ```
 
-You can also mount the admin engine to manage and analyze your experiments via the built-in admin UI. You'll probably want to wrap this in some sort of authentication, though the details will vary between applications. If you're already mounting other admin engines (i.e. something like `sidekiq` or `flipper`), you should be able to apply the same technique to trailguide.
+Or you can create a config initializer, which is useful if you plan on configuring TrailGuide further:
 
 ```ruby
-# /config/routes.rb
-
-Rails.application.routes.draw do
-  # ...
-
-  mount TrailGuide::Engine => 'api/experiments'
-
-  # example auth route helper
-  authenticate :user, lambda { |u| u.admin? } do
-    mount TrailGuide::Admin::Engine => 'admin/trailguide'
-  end
+# config/initializers/trailguide.rb
 
-  # ...
+TrailGuide.configure do |config|
+  config.redis = 'redis://127.0.0.1:6379'
+  # or you can also use your own client
+  # config.redis = Redis.new(url: 'redis://127.0.0.1:6379')
 end
 ```
 
@@ -67,23 +70,23 @@ Create and configure an experiment:
 experiment :simple_ab do |config|
   config.summary = "This is a simple A/B test" # optional
 
-  variant :a
-  variant :b
+  variant :alpha # the first variant is always the "control" group unless declared otherwise
+  variant :bravo
 end
 ```
 
-Start your experiment either via the admin UI or from a rails console with `TrailGuide.catalog.find(:simple_ab).start!` to enable enrollment.
-
-Then use it (in controller actions for this example):
+Then use it in controller:
 
 ```ruby
+# app/controllers/things_controller.rb
+
 def show
   # enroll in the experiment and do something based on the assigned variant group
-  case trailguide.choose(:simple_ab)
-    when :a
-      # perform logic for group "a"
-    when :b
-      # perform logic for group "b"
+  case trailguide(:simple_ab)
+    when :alpha
+      # perform your logic for group "alpha"
+    when :bravo
+      # perform your logic for group "bravo"
   end
 
   # ...
@@ -97,11 +100,60 @@ def update
 end
 ```
 
-If you've mounted the admin engine, you can view your experiment's participants and conversions there.
+Or a view:
+
+```erb
+# app/views/things/show.html.erb
+
+<% if trailguide(:simple_ab) == :alpha %>
+  <div>...render alpha...</div>
+<% else %>
+  <div>...render bravo...</div>
+<% end %>
+```
+
+TODO link to examples of `run`, `render`, etc.
+
+Until your experiment is started, only the "control" group (in this case `:alpha`) will be served to visitors. Start your experiment either via the admin UI or from a rails console with `TrailGuide.catalog.find(:simple_ab).start!` to begin enrolling participants and serving variants.
+
+### API / JavaScript Client
+
+If you plan on using the included javascript client, or if you just want an API to interact with experiments in other ways, you can mount the engine in your route config:
+
+```ruby
+# config/routes.rb
+
+Rails.application.routes.draw do
+
+  mount TrailGuide::Engine => 'api/experiments'
+
+  # ...
+end
+```
+
+### Admin UI
+
+You can also mount the admin engine to manage and analyze your experiments via the built-in admin UI. You'll probably want to wrap this in some sort of authentication, although the details will vary between applications. If you're already mounting other admin engines (i.e. something like `sidekiq` or `flipper`), you should be able to apply the same technique to trailguide.
+
+```ruby
+# config/routes.rb
+
+Rails.application.routes.draw do
+
+  mount TrailGuide::Engine => 'api/experiments'
+
+  # example auth route helper
+  authenticate :user, lambda { |u| u.admin? } do
+    mount TrailGuide::Admin::Engine => 'admin/trailguide'
+  end
+
+  # ...
+end
+```
 
 ## Configuration
 
-The core engine and base experiment class have a number of configuration options available to customize behavior and hook into various pieces of functionality. The best way to configure trailguide is via a config initializer, and this gem configures it's own defaults the same way.
+The core engine and base experiment class have a number of configuration options available to customize behavior and hook into various pieces of functionality with callbacks. The best way to configure trailguide is via a config initializer, and this gem configures it's own defaults the same way.
 
 ```ruby
 # config/initializers/trailguide.rb
@@ -112,20 +164,43 @@ TrailGuide.configure do |config|
 end
 
 TrailGuide::Experiment.configure do |config|
+  # all experiments inherit from the top-level experiment class,
+  # which allows you to provide global experiment configuration
+  # here, and override custom behavior on a per-experiment basis
   config.algorithm = :weighted
   # ...
 end
 ```
 
-Take a look at [`config/initializers/trailguide.rb`](https://github.com/markrebec/trailguide/blob/master/config/initializers/trailguide.rb) in this repo for a full list of defaults and examples of the available configuration options.
+Take a look at [`the config initializers in this repo`](https://github.com/markrebec/trailguide/blob/master/config/initializers) for a full list of defaults and examples of the available configuration options.
 
 ### Configuring Experiments
 
 Before you can start running experiments in your app you'll need to define and configure them. There are a few options for defining experiments - YAML files, a ruby DSL, or custom classes - and they all inherit the base `TrailGuide::Experiment.configuration` for defaults, which can be overridden per-experiment.
 
+#### Experiments Paths
+
+By default, TrailGuide will look for experiment configs in `config/experiments.*` and `config/experiments/**/*`, and will load custom experiment classes from `app/experiments/**/*`. You can override this behavior with the `TrailGuide.configuration.paths` object in your config initializer.
+
+```ruby
+# config/initializers/trailguide.rb
+
+TrailGuide.configure do |config|
+  # you can append a single file or a glob pattern onto the experiment config loadpaths
+  config.paths.configs << 'foo/bar/experiments/**/*'
+
+  # or you can explicitly override the values with your own
+  config.paths.configs = ['foo/bar/baz.rb', 'other/path/**/*']
+
+  # you can also append or override the path(s) from which custom experiment classes are loaded
+  config.paths.classes = ['lib/experiments/**/*']
+end
+
+```
+
 #### YAML
 
-YAML files are an easy way to configure simple experiments. They can be put in `config/experiments.yml` or `config/experiments/**/*.yml`:
+YAML files are an easy way to configure simple experiments. They will be loaded based on your path configurations above, and by default can be put in `config/experiments.yml` or `config/experiments/**/*.yml`:
 
 ```yaml
 # config/experiments.yml
@@ -150,7 +225,7 @@ search_widget:
 
 #### Ruby DSL
 
-The ruby DSL provides a more dynamic and flexible way to configure your experiments, and allows you to define custom behavior via callbacks and options. You can put these experiments in `config/experiments.rb` or `config/experiments/**/*.rb`:
+The ruby DSL provides a more dynamic and robust way to configure your experiments, allowing you to define custom behavior via callbacks and other options. Like YAML experiments, they're loaded based on your path configurations, and by default You can put these experiments in `config/experiments.rb` or `config/experiments/**/*.rb`:
 
 ```ruby
 # config/experiments.rb
@@ -180,9 +255,9 @@ end
 
 #### Custom Classes
 
-You can also take it a step further and define your own custom experiment classes, inheriting from `TrailGuide::Experiment`. This allows you to add or override all sorts of additional behavior on top of all the standard configuration provided by the DSL. In fact, the YAML and ruby DSL configs both use this to parse experiments into anonmymous classes extending `TrailGuide::Experiment`.
+You can also take it a step further and define your own custom experiment classes, inheriting from `TrailGuide::Experiment`. This allows you to add or override all sorts of additional behavior on top of all the standard configuration provided by the DSL. In fact, the YAML and ruby DSL configs both use this to parse experiments into anonmymous classes inheriting from `TrailGuide::Experiment`.
 
-You can put these classes anywhere rails will autoload them (or require them yourself), but I recommend `app/experiments/**/*.rb`:
+You can put these classes anywhere rails will autoload them (i.e. `app/whatever`), or you can put them somewhere like `lib/experiments` and require them yourself, but TrailGuide will also attempt to load them for you based on your path configurations, which by default looks in `app/experiments/**/*.rb`:
 
 ```ruby
 # app/experiments/my_complex_experiment.rb
@@ -251,218 +326,11 @@ You can even use these in your DSL-defined experiments by specifying a `class:`
 # config/experiments.rb
 
 experiment :my_inheriting_experiment, class: ApplicationExperiment do |config|
-  # ...
-end
-```
-
-### Participant Adapters
-
-While all experiment configuration, metadata and metrics are stored in redis, there are various adapters available for participants to control where individual assignments are stored for each user. These adapters are configurable and extensible, so you can customize them or even create your own by following a simple interface.
-
-The following participant adapters are included with trailguide:
-
-* `:cookie` (default) - stores participant assignments in a cookie in their browser
-* `:session` - stores participant assignments in a hash in their rails session
-* `:redis` - stores participant assignments in redis, under a configurable key identifier (usually `current_user.id` or a cookie storing some sort of tracking/visitor ID for logged out users)
-* `:anonymous` - temporary storage, in a local hash, that only exists for as long as you have a handle on the participant object (usually a last resort fallback)
-* `:multi` - attempts to use the "best" available adapter based on the current context
-* `:unity` - uses `TrailGuide::Unity` to attempt to unify visitor/user sessions based on your configuration
-
-#### Cookie
-
-This is the default adapter, which stores participation details in a cookie in the user's browser. If you want to configure the cookie name, path or expiration, you can do so directly in your initializer:
-
-```ruby
-TrailGuide.configure do |config|
-  # config.adapter = :cookie
-  config.adapter = TrailGuide::Adapters::Participants::Cookie.configure do |config|
-    config.cookie = :trailguide
-    config.path = '/'
-    config.expiration = 1.year.to_i
-  end
-end
-```
-
-#### Session
-
-The session adapter will store participation in a hash under a configurable key within the user's rails session.
-
-```ruby
-TrailGuide.configure do |config|
-  # use the symbol shortcut for defaults
-  config.adapter = :session
-
-  # or configure it
-  config.adapter = TrailGuide::Adapters::Participants::Session.configure do |config|
-    config.key = :trailguide
-  end
-end
-```
+  # you can configure this experiment just like any other DSL-based experiment,
+  # the only difference is that the resulting anonymous class will inherit from
+  # ApplicationExperiment rather than directly from TrailGuide::Experiment
 
-#### Redis
-
-The redis adapter stores participation details in a configurable redis key, which makes it great for ensuring consistency across visits and even devices. While the cookie and session adapters are restricted to a single browser or even a single browsing session, the redis adapter is more persistent and controllable, with the tradeoff being that you'll need to be able to identify your users in some way (i.e. `current_user.id`).
-
-```ruby
-TrailGuide.configure do |config|
-  # use the symbol shortcut for defaults
-  config.adapter = :redis
-
-  # or configure it
-  config.adapter = TrailGuide::Adapters::Participants::Redis.configure do |config|
-    config.namespace = :participants
-    config.expiration = nil
-    config.lookup = -> (context) { # context is wherever you're invoking trailguide, usually a controller or view
-      context.try(:trailguide_user).try(:id) ||
-        context.try(:current_user).try(:id)
-    }
-  end
-end
-```
-
-#### Anonymous
-
-The anonymous adapter is a simple, ephemeral ruby hash that only exists for as long as you have a reference to that local participant object. It's generally only used as a last resort when there's no way to identify a participant who is enrolling in an experiment, because there's no way to get a new reference later on (for example to track conversion).
-
-#### Multi
-
-The multi adapter will attempt to use the "best" available adapter, depending on the context from which trailguide is being invoked (controller, view, background job, etc.). It comes with a default configuration that prefers to use redis if a `trailguide_user` or `current_user` is available, otherwise tries to use cookies if possible, then session if possible, falling back to anonymous as a last resort.
-
-You can use the multi adapter to wrap any adapter selection logic you like, the only requirement is that you return one of the other adapters:
-
-```ruby
-TrailGuide.configure do |config|
-  # use the symbol shortcut for defaults
-  config.adapter = :multi
-
-  # or configure it
-  config.adapter = TrailGuide::Adapters::Participants::Multi.configure do |config|
-    # should be a proc that returns another adapter to be used
-    config.adapter = -> (context) do
-      if (context.respond_to?(:trailguide_user, true) && context.send(:trailguide_user).present?) ||
-          (context.respond_to?(:current_user, true) && context.send(:current_user).present?)
-        TrailGuide::Adapters::Participants::Redis
-      elsif context.respond_to?(:cookies, true)
-        TrailGuide::Adapters::Participants::Cookie
-      elsif context.respond_to?(:session, true)
-        TrailGuide::Adapters::Participants::Session
-      else
-        TrailGuide::Adapters::Participants::Anonymous
-      end
-    end
-  end
-end
-```
-
-#### Unity
-
-The unity adapter is a wrapper around `TrailGuide::Unity`, which attempts to unify user/visitor sessions, then selects and configures the appropriate adapter. It looks for an available, configurable "user ID" (`current_user`) and "visitor ID" (from a cookie) and configures the redis adapter appropriately. If there is no identifying information available it falls back to the anonymous adapter.
-
-You can configure the visitor cookie and the user id attribute, as well as the adapters to be used in each case:
-
-```ruby
-TrailGuide.configure do |config|
-  config.adapter = TrailGuide::Adapters::Participants::Unity.configure do |config|
-    # setup the visitor ID cookie and user ID attribute
-    config.visitor_cookie = :visitor_id # uses a cookie called visitor_id, must be set and managed by you separately
-    config.user_id_key = :uuid # uses current_user.uuid, defaults to current_user.id
-
-    # uses redis adapter for identified users
-    config.user_adapter = TrailGuide::Adapters::Participants::Redis.configure do |config|
-      config.namespace = 'unity:users'
-      config.lookup = -> (user_id) { user_id }
-      config.expiration = 1.year.seconds
-    end
-
-    # uses redis adapter for identified visitors
-    config.visitor_adapter = TrailGuide::Adapters::Participants::Redis.configure do |config|
-      config.namespace = 'unity:visitors'
-      config.lookup = -> (visitor_id) { visitor_id }
-      config.expiration = 1.year.seconds
-    end
-
-    # uses anonymous adapter for unidentified
-    config.anonymous_adapter = TrailGuide::Adapters::Participants::Anonymous
-  end
-end
-```
-
-See the unity documentation for more info about unifying sessions.
-
-#### Custom Adapters
-
-**TODO** - In the meantime, checkout the cookie or session adapters for simple examples as a starting point.
-
-```ruby
-TrailGuide.configure do |config|
-  config.adapter = MyCustom::AdapterClass
-end
-```
-
-### Algorithms
-
-There are a few common assignment algorithms included in trailguide, and it's easy to define your own and configure your experiments to use them. Algorithms can either be configured globally for all experiments in your initializer, or overridden individually per-experiment.
-
-The following algorithms are available:
-
-* `:weighted` (default) - allows favoring variants by assigning them weights
-* `:distributed` - totally even distribution across variants
-* `:random` - truly random sampling of variants on assignment
-* `:bandit` - a "multi-armed bandit" approach to assignment
-
-#### Weighted
-
-This is the default algorithm, which allows weighted assignment to variants based on each variant's configuration. All things being equal (all variants having equal weights), it's essentially a random sampling that will provide mostly even distribution across a large enough sample size. The default weight for all variants is 1.
-
-```ruby
-experiment :my_experiment do |config|
-  config.algorithm = :weighted
-
-  variant :a, weight: 2 # would be assigned roughly 40% of the time
-  variant :b, weight: 2 # would be assigned roughly 40% of the time
-  variant :c, weight: 1 # would be assigned roughly 20% of the time
-end
-```
-
-Note that the weighted algorithm is the only one that takes variant weight into account, and the other algorithms will simply ignore it if it's defined.
-
-#### Distributed
-
-The distributed algorithm ensures completely even distribution across all variants by always selecting from the variant(s) with the lowest number of participants.
-
-```ruby
-experiment :my_experiment do |config|
-  config.algorithm = :distributed
-end
-```
-
-#### Random
-
-The random algorithm provides totally random distribution by sampling from all variants on assignment.
-
-```ruby
-experiment :my_experiment do |config|
-  config.algorithm = :random
-end
-```
-
-#### Multi-Armed Bandit
-
-The bandit algorithm in trailguide was heavily inspired by [the split gem](https://github.com/splitrb/split#algorithms), and will automatically weight variants based on their performance over time. You can [read more about this approach](http://stevehanov.ca/blog/index.php?id=132) if you're interested.
-
-```ruby
-experiment :my_experiment do |config|
-  config.algorithm = :bandit
-end
-```
-
-#### Custom
-
-**TODO** - In the meantime, take a look at the included algorithms as a starting point. Essentially as long as you accept an experiment and return a variant, the rest is up to you.
-
-```ruby
-experiment :my_experiment do |config|
-  config.algorithm = MyCustom::AlgorithmClass
+  # ...
 end
 ```
 
@@ -470,16 +338,16 @@ end
 
 ### Helpers
 
-The `TrailGuide::Helper` module is available to be mixed into just about any context, and provides a helper proxy with an easy API to interact with trailguide. These helpers are mixed into controllers and views as helper methods by default. You can disable this behavior by setting the `config.include_helpers` option to `false` if you'd rather explicitly include it where you want to use it.
+The `TrailGuide::Helper` module is available to be mixed into just about any context, and provides an easy way to interact with TrailGuide experiments. These helpers are mixed into controllers and views as helper methods by default, but you can disable this behavior by setting the `config.include_helpers` option to `false` if you'd rather explicitly include it where you want to use it.
 
-When mixed in, the `trailguide` method provides a reference to the helper proxy, which in turn provides a few methods to perform your experiments.
+When mixed in, the `trailguide` method provides a reference to the helper proxy, which in turn provides a few methods to interact with your experiments.
 
 ```ruby
 # enroll in an experiment or reuse previous assignment
 trailguide.choose(:experiment_name)
 trailguide.choose!(:experiment_name)
 
-# choose, then automatically calls a method within the current context based on
+# chooses, then automatically calls a method within the current context based on
 # the selected variant
 trailguide.run(:experiment_name)
 trailguide.run!(:experiment_name)
@@ -489,7 +357,7 @@ trailguide.run!(:experiment_name)
 trailguide.render(:experiment_name)
 trailguide.render!(:experiment_name)
 
-# tracks a conversion for the participant's currently assigned variant
+# tracks a conversion only if participating, for the participant's currently assigned variant
 trailguide.convert(:experiment_name)
 trailguide.convert!(:experiment_name)
 ```
@@ -498,7 +366,7 @@ As a general rule of thumb, the bang (`!`) methods will loudly raise exceptions
 
 #### Enrollment
 
-The `choose` method will either enroll a participant into an experiment for the first time or return their previously assigned variant if they've already been enrolled. It can accept a block to execute and returns a `TrailGuide::Variant` object, but can be compared directly to strings or symbols.
+The `choose` method will either enroll a participant into an experiment for the first time or return their previously assigned variant if they've already been enrolled. It can accept an optional block to execute, and returns a `TrailGuide::Variant` object, *which can be compared directly to strings or symbols* or access it's properties directly (i.e. `variant.metadata[:foo]`).
 
 ```ruby
 class MyController < ApplicationController
@@ -535,7 +403,7 @@ class MyController < ApplicationController
 end
 ```
 
-You can also call `trailguide.choose` from your view templates, though you probably want to keep any complex logic in your controllers (or maybe helpers). This would print out the variant name into an `h1`:
+You can also call `trailguide.choose` from your view templates and partials, though you probably want to keep any complex logic in your controllers (or maybe helpers). This would print out the variant name into an `h1`:
 
 ```erb
 <% variant = trailguide.choose(:experiment_name) %>
@@ -544,7 +412,7 @@ You can also call `trailguide.choose` from your view templates, though you proba
 
 #### Running Methods
 
-If you prefer, you can encapsulate your logic into methods for each variant and ask trailguide to execute the appropriate one for you automatically.
+If you prefer, you can encapsulate your logic into methods for each variant and ask trailguide to execute the appropriate one for you automatically within the given context.
 
 ```ruby
 class MyController < ApplicationController
@@ -565,25 +433,26 @@ class MyController < ApplicationController
 end
 ```
 
-By default the above will attempt to call methods with a name matching your variant name, but you can configure custom methods via the `methods:` keyword argument.
+By default the above will attempt to call methods with a name matching your assigned variant name, but you can configure custom methods via the `methods:` keyword argument.
 
 ```ruby
 class MyController < ApplicationController
   def index
     # this would call one of the methods below depending on assignment
-    trailguide.run(:experiment_name, methods: {
-      variant_one: :my_first_method,
-      variant_two: :my_second_method
-    },
-    metadata: {
-      # you can also optionally pass custom metadata through to choose
-    })
+    trailguide.run(:experiment_name,
+      methods: {
+        variant_one: :my_first_method,
+        variant_two: :my_second_method
+      },
+      metadata: {
+        # you can also optionally pass custom metadata through
+      })
   end
 
   private
 
   def my_first_method(**metadata)
-    # ... do whatever, maybe use these almost like a `before_filter` to setup instance vars
+    # ... do whatever - you could use these almost like a `before_filter` to setup different instance vars depending on assignment
   end
 
   def my_second_method(**metadata)
@@ -596,7 +465,7 @@ You **can** use `trailguide.run` in your views, but the methods you're calling m
 
 #### Rendering
 
-Many experiments include some sort of UI component, and trailguide provides a handy shortcut to render different paths when that pattern suits your needs. The `trailguide.render` method can be used in controllers to render templates or in views to render partials, and uses rails' underlying render logic for each context.
+Many experiments include some sort of UI component, and trailguide provides a handy shortcut to automatically render different templates/partials when that pattern suits your needs. The `trailguide.render` method can be used in controllers to render templates or in views to render partials, and uses rails' underlying render logic for each context.
 
 ```ruby
 # config/experiments/homepage_ab.rb
@@ -677,7 +546,7 @@ trailguide.convert(:experiment_name, :goal_name)
 
 The way you use trailguide outside of a request context will mostly depend on the participant adapter being used. To get started, you'll need to include the `TrailGuide::Helper` module into whatever class or context you're working with.
 
-The `:cookie` and `:session` adapters **will not work** in a background context, but the default `:redis`, `:multi` and `:unity` adapters will work if provided with a `trailguide_user`. This assumes that the `trailguide_user` matches whatever user you're assigning within your request contexts (which is commonly `current_user`) if you want assignments to match up and be consistent, and the default configurations for these supported adapters all look for either a `trailguide_user` or a `current_user` so they should work in most contexts.
+The `:cookie` and `:session` adapters **will not work** in a background context, but the default `:redis`, `:multi` and `:unity` adapters will work if provided with a `trailguide_user`. This assumes that the `trailguide_user` matches the same user elsewhere in your request contexts (like in your controllers and views), which is commonly `current_user`. The default configurations for these supported adapters all look for either a `trailguide_user` or a `current_user` so they should work in most contexts.
 
 A simple example might be sending a welcome email in a background job with a variable discount amount depending on what variant the user was enrolled into during signup.
 
@@ -741,11 +610,7 @@ client.convert('experiment_name', 'optional_goal');
 client.active();
 ```
 
-## Experiment Lifecycle
-
-**TODO**
-
-## Goals
+## Conversion Goals
 
 You can configure experiment goals if a single experiment requires multiple conversion goals, or if you just want to define a single named goal to be more explicit.
 
@@ -759,8 +624,8 @@ experiment :button_color do |config|
   goal :checked_out
 
   # if this is false (default), once a participant converts to one of the defined goals, they will not be able to convert to any of the others unless the experiment is reset
-  # if this is true, a single participant may convert to more than one goal, but only once each
-  config.allow_multiple_goals = false
+  # if this is true, a single participant may convert to more than one goal, but only once each, which allows for simple conversion funnels
+  config.allow_multiple_goals = true
 end
 ```
 
@@ -770,7 +635,7 @@ When you define one or more named goals for an experiment, you must pass one of
 trailguide.convert(:button_color, :signed_up)
 ```
 
-## Groups
+## Conversion Groups
 
 If you have multiple experiments that share a relevant conversion point, you can configure them with a shared group. This allows you to reference and convert multiple experiments at once using that shared group, and only experiments in which participants have been enrolled will be converted.
 
@@ -813,15 +678,15 @@ end
 
 ### Orphaned Groups
 
-Sometimes in the real world, you might accidentally remove all the experiments that were sharing a given group, but miss one of the conversion calls that used one of it's groups. Maybe you forgot to search through your code for references to the group, or maybe you just didn't know you were removing the last experiment in that group. Ideally you'd be testing your code thoroughly, and you'd catch the problem before hitting production, but trailguide has a built-in safe guard just in case.
+Sometimes in the real world, you might accidentally remove all the experiments that were sharing a given group, but miss one of the conversion calls that used one of those groups. Maybe you forgot to search through your code for references to the group, or maybe you just didn't know you were removing the last experiment in that group. Ideally you'd be testing your code thoroughly, and you'd catch the problem before hitting production, but trailguide has a built-in safe guard just in case.
 
-Instead of raising a `TrailGuide::NoExperimentsError` when no experiments match your arguments like `trailguide.choose` and related methods do, the `trailguide.convert` method will log a warning and return `false` as if no conversion happened.
+Instead of raising a `TrailGuide::NoExperimentsError` when no experiments match your arguments like the `trailguide.choose` and related methods do, the `trailguide.convert` method will log a warning and return `false` as if no conversion happened.
 
 After a failed conversion for an orphaned group, the next time you visit the trailguide admin dashboard you'll see an alert with the details of any logged orphaned groups. If you wish to ignore orphaned groups entirely, perhaps so you can leave conversion calls in your application while you regularly rotate experiments into and out of those groups, you can set the `TrailGuide.configuration.ignore_orphaned_groups = true` config option in your initializer.
 
 ### Groups with Goals
 
-Since grouping is only useful when converting, and experiments with defined goals require a goal to be passed in when converting, **any experiments that are sharing a group must define the same goals in order to be converted together.** Not all goals need to overlap, but you will only be able to convert goals that are shared when referencing a group.
+Since grouping is primarily useful when converting, and experiments with defined goals require a goal to be passed in when converting, **any experiments that are sharing a group must define the same goals in order to be converted together.** Not all goals need to overlap, but you will only be able to convert goals that are shared when referencing a group.
 
 If you're grouping your experiments, that probably means you have multiple experiments that are all being used in the same area of your app and therefore are likely sharing the same (or similar) conversion goals. You can assign your groups and goals the same names to make converting easier by referencing a single key:
 
@@ -830,8 +695,8 @@ experiment :first_search_experiment do |config|
   variant :alpha
   variant :bravo
 
-  config.groups = [:click_search, :click_banner, :search_experiments]
-  config.goals  = [:click_search, :click_banner, :custom_goal]
+  groups :click_search, :click_banner, :search_experiments
+  goals  :click_search, :click_banner, :custom_goal
 end
 
 experiment :second_search_experiment do |config|
@@ -839,24 +704,24 @@ experiment :second_search_experiment do |config|
   variant :two
   variant :three
 
-  config.groups = [:click_search, :click_banner, :search_experiments]
-  config.goals  = [:click_search, :click_banner, :some_other_goal]
+  groups :click_search, :click_banner, :search_experiments
+  goals  :click_search, :click_banner, :some_other_goal
 end
 
 experiment :third_search_experiment do |config|
   variant :red
   variant :blue
 
-  config.groups = [:click_search, :click_banner, :search_experiments]
-  config.goals  = [:click_search, :click_banner]
+  groups :click_search, :click_banner, :search_experiments
+  goals  :click_search, :click_banner
 end
 
 # then to convert all three experiments for the click_search group, against the
 # click_search goal
 trailguide.convert(:click_search)
 
-# the above is the equivalent of calling their group name (in this case not
-# matching the goal name) and the goal name
+# the above is the equivalent of calling them by a shared group name (in this example
+# the :search_experiments group) and the conversion goal name
 trailguide.convert(:search_experiments, :click_search)
 
 # or the equivalent of converting each of the three experiments individually
@@ -870,6 +735,39 @@ trailguide.convert(:third_search_experiment, :click_search)
 trailguide.convert(:first_search_experiment, :custom_goal)
 ```
 
+### Metrics
+
+Metrics are a quick way to combine groups and goals and remove some of the boilerplate when sharing them between experiments. Using the `metrics` config, we can simplify the above examples a bit:
+
+```ruby
+experiment :first_search_experiment do |config|
+  variant :alpha
+  variant :bravo
+
+  metrics :click_search, :click_banner  # this configures a group and a goal for each metric
+  group   :search_experiments           # add another group (without a goal)
+  goal    :custom_goal                  # add another goal (without a group)
+end
+
+experiment :second_search_experiment do |config|
+  variant :one
+  variant :two
+  variant :three
+
+  metrics :click_search, :click_banner  # this configures a group and a goal for each metric
+  group   :search_experiments           # add another group (without a goal)
+  goal    :some_other_goal              # add another goal (without a group)
+end
+
+experiment :third_search_experiment do |config|
+  variant :red
+  variant :blue
+
+  metrics :click_search, :click_banner  # this configures a group and a goal for each metric
+  group   :search_experiments           # add another group (without a goal)
+end
+```
+
 ## Combined Experiments
 
 **TODO**