mobiusloop 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0e6bd4113018108ce0d474e02243c13e5e8701f9
-  data.tar.gz: ccda4bfa5a8026be4c646f884cf5aaaf8b8275d0
+  metadata.gz: cc0c13ef43aafb60ae151d24308f553385c76ea4
+  data.tar.gz: d3cc8fddea44193199a35da90ffa1d839d706f79
 SHA512:
-  metadata.gz: 8fc115d1b44f03d233997ee9dde71744b75ae8377bbf6e6b5d9d1ab1abf22d3f275fc0f76cd523783b1c8a51d0fa1212c37d23ccc3ce71e78322d1dc6896eaf7
-  data.tar.gz: 8b20b671d419e975385d6e7ea87bf98fad1475c16648be055cd3f0f85d00778240617f5fc105fe6731114fb48e6830992d5a342d821bcfbbbb3de3af61e1f2d9
+  metadata.gz: 472298f62f78c1795e98f232738d146705854208789bfebab79298cd0041beb27ae36ec6a46454a809e1f36625ab72db7239cf629037879faf5249d0502b1e34
+  data.tar.gz: b1a8bf86d267231a68f7e866463649a0d836f601c70541dd1bef899996a88ac64258198cabf22bafe522ac09d2df7444b66777a508e6887144ed3a8fa78d249f

data/Gemfile

@@ -1,5 +1,5 @@
-gem "cucumber-pro", "0.0.13", :group => :test
+gem "cucumber-pro", "0.0.13"
 source "https://rubygems.org"
-gemspec
+gemspec :name => 'mobiusloop'
 
 gem 'mime-types', '~>2.99'

data/README.md

@@ -1,18 +1,19 @@
-# building the right things with mobiusloop
+# building the right things with mobius
 
-`mobiusloop` provides continuous feedback to people on whether they are **building the right things**, not just **building things right**.
+`mobius` provides continuous feedback to people on whether they are **building the right things**, not just **building things right**.
 
 Most product development tools focus on **building things right** meaning on time, on budget and with high quality.
-`mobiusloop` is different. It uses a simple language to define the desired business and product goals, such as Increase
-Customer Conversion or Improve App Responsiveness. Then `mobiusloop` uses automation to measure and report on progress
-towards these goals daily, weekly or whenever you want.
+`mobius` is different. It uses a simple language to define the desired business and product goals, such as Increase
+Customer Conversion or Improve App Responsiveness. Then `mobius` uses automation to measure and report on progress
+towards these goals whenever you want.
 
-With `mobiusloop` teams get realtime feedback on whether their new features are delivering the expected value. Leaders get
+With `mobius` teams get realtime feedback on whether their new features are delivering the expected value. Leaders get
 clear visibility on whether their investments are delivering the desired return. Everyone gets feedback on whether they are
 **building the right things**.
 
-Use `mobiusloop` with methods like [Objectives and Key Results (OKR's)](https://www.amazon.com/Radical-Focus-Achieving-Important-Objectives-ebook/dp/B01BFKJA0Y)
-and [Mobius](http://mobiusloop.com) to define and measure the value of your product or service.
+Use `mobius` with our method [Mobius](http://mobiusloop.com) and other methods like
+[Objectives and Key Results (OKR's)](https://www.amazon.com/Radical-Focus-Achieving-Important-Objectives-ebook/dp/B01BFKJA0Y)
+to define and measure the value of your product or service.
 
 
 ## how it works
@@ -21,10 +22,10 @@ Today many teams write automated feature tests using open source tools like [Cuc
 tests in a simple, readable format using the [Gherkin](https://cucumber.io/docs/reference) language. Whenever these tests are run, teams get realtime feedback
 on the quality of their product.
 
-`mobiusloop` takes this concept and applies it to strategic business and product goals. Instead of tests that report on
-product quality when run, `mobiusloop` reports on progress towards desired goals.
+`mobius` builds up this concept to apply automation towards product goals and business objectives. Instead of tests that report on
+product quality, `mobius` reports on progress towards desired goals.
 
-Under the covers `mobiusloop` is built on [Cucumber](http://cucumber.io) and consists of three main parts:
+Under the covers `mobius` is built on the popular open source testing tool [Cucumber](http://cucumber.io). It consists of three main parts:
  1. `.goal` files
  1. step definitions
  1. custom `Scale`'s
@@ -36,7 +37,7 @@ Frameworks like [Objectives and Key Results (OKR's)](https://www.amazon.com/Radi
 and [Mobius](http://mobiusloop.com) encourage qualitative statements (problems or objectives) together with quantitative
 measures of success (outcomes or key results).
 
-Using `mobiusloop`, leaders and teams collaboratively write these in a `.goal` text file. Here's an example:
+Using `mobius`, leaders and teams collaboratively write these in a `.goal` text file. Here's an example:
 
 ```ruby
 Objective: Reach a million paying customers by Q3 2016!
@@ -44,8 +45,7 @@ Objective: Reach a million paying customers by Q3 2016!
   Key Result: Increase Journal Readership
     Given a baseline of 500,000 readers on Oct 1, 2015
     And a target of 1,000,000 readers by Oct 1, 2016
-    When we measure progress with "Total Readers Scale"
-    Then report progress towards target
+    Then measure progress with "Total Readers Scale"
 ```
 Here's another one:
 
@@ -55,15 +55,14 @@ Problem: Slow app response times are causing us to lose customers
   Outcome: Improve App Responsiveness
     Given a baseline of 4.5 seconds average response time on May 1, 2016
     And a target of 1.5 seconds average response time by Jun 30, 2016
-    When we measure progress with "Peak User Performance Scale"
-    Then report progress towards target
+    Then measure progress with "Peak User Performance Scale"
 ```
 The syntax is based [Gherkin](https://cucumber.io/docs/reference), the language used to write Cucumber acceptance tests.
-`mobiusloop` introduces a four new keywords to Gherkin: **Objective**, **Problem**, **Outcome** and **Key Result**.
+`mobius` introduces a four new keywords to Gherkin: **Objective**, **Problem**, **Outcome** and **Key Result**.
 
 Each `.goal` file contains **one** Objective or Problem and **one or more** Outcomes or Key Results.
 
-When the `.goal` files are run from a command line, they report progress towards your targets like this:
+When the `.goal` files are run with `mobius`, they report progress towards your targets like this:
 
 ```ruby
 Objective: Top a million paying customers by Q3 2016!
@@ -73,45 +72,45 @@ Objective: Top a million paying customers by Q3 2016!
     And a target of 1000000 readers by "Oct 1, 2016"
     When we measure progress with "Total Readers Scale"
       Success! found 820,000 readers in 1.2 seconds!
-    Then report progress towards targets
+    Then measure progress with "Total Readers Scale"
       Hooray! You are on track!
       64% progress to target using 61% of the time (222 days)
       36% remaining to target in 143 days
 ````
 
-Progress is reported as text or optionally saved in a [web page](results.html) for sharing.
+Progress is reported on the screen an optionally saved to a file.
 
-With `mobiusloop` teams can measure progress towards their goals daily, weekly, monthly or whatever cadence makes sense.
-Integrating `mobiusloop` into your continuous delivery pipeline helps measure the impacts of each new release on your outcomes or key results.
+With `mobius` teams can measure progress towards their goals daily, weekly, monthly or whatever cadence makes sense.
+Integrating `mobius` into your continuous delivery pipeline helps measure the impacts of each new release on your outcomes or key results.
 
 
 #### 2. step definitions
-Under the covers, `mobiusloop` is built on a forked copy of [cucumber-ruby](https://github.com/cucumber/cucumber-ruby).
-It uses Gherkin to parse the `.goal` file and call Cucumber [step definitions](https://github.com/cucumber/cucumber/wiki/Step-Definitions).
-`mobiusloop` ships with one step definition [mobius_steps.rb](lib/mobiusloop/mobius_steps.rb) that can be modified or extended.
+Under the covers, `mobius` is built on a forked copy of [cucumber-ruby](https://github.com/cucumber/cucumber-ruby).
+It uses Gherkin to parse the `.goal` files and call Cucumber [step definitions](https://github.com/cucumber/cucumber/wiki/Step-Definitions).
+`mobius` ships with one step definition [mobius_steps.rb](lib/mobiusloop/mobius_steps.rb) that can be modified or extended.
 
-In `mobius_steps.rb`, the lines beginning with `Given` save the baseline and target values.
+Inside `mobius_steps.rb`, the lines beginning with `Given` and `And` save the baseline and target values, respectively.
 The line beginning with `When` creates an `Outcome` with a custom `Scale`, sets the baselines and targets, then calls
 the `measure` method to perform the measurement. The line beginning with `Then` reports the progress towards targets.
 
 This `Given, When, Then` syntax is identical to Gherkin, easing the learning curve for teams already using Cucumber.
-Teams can either use `mobius_steps.rb` or create their own step definitions.
+Teams can choose to use the built-in `mobius_steps.rb` or create their own step definitions.
 
 
 #### 3. custom `Scale`'s
 
 At creation time, each outcome (or key result) is associated with a custom `Scale` of measure.
-`Scale`'s are the code that collects your data in your environment to report progress.
-`mobiusloop` ships with a few example scales, however teams are encouraged to create custom scales to meet their needs.
+Scale's are the code that collects your data in your environment to report progress.
+`mobius` ships with a few example scales, however teams are encouraged to create custom scales to meet their needs.
 
 To create a Scale, create a new Ruby class that extends `Scale` and then implement the `measure` method. Next, update the `.goal`
- file to reference your new `Scale` class. When `mobiusloop` parses this line:
+ file to reference your new `Scale` class. When `mobius` parses this line:
 
 ```we measure progress with "Total Readers Scale"```
 
 it creates a new instance of the Ruby class `TotalReadersScale` and calls the `measure` method, which returns a new `Measure`.
 
-In this example, you would implement the method `collect_total_readers` with your custom logic.
+Here's an example:
 
 ```Ruby
 require 'mobiusloop/scale'
@@ -126,147 +125,189 @@ class TotalReadersScale < Scale
 end
 ````
 
+In this example you would implement the method `collect_total_readers` with your custom logic.
+
 
 ## getting started
 
-Adding `mobiusloop` to your product is easy, but requires some command-line chops.
-If this section looks like Greek, then as nicely as possible ask a developer on your team for help.
+Adding `mobius` to your product is relatively easy, but requires some command-line chops and about 20 minutes of your time.
+If the following section looks like Greek, then as nicely as possible ask a developer on your team for help. Come bearing gifts!
 
 **Note:** Currently only Ruby on Linux and OSX are tested platforms. Windows will be added in the future.
 
 If [Ruby](https://www.ruby-lang.org/en/), [gem](https://rubygems.org) and [bundle](http://bundler.io) are not installed, install them first.
 
-Then install `mobiusloop` with this command:
+Then install `mobius` with this command:
 
     $ gem install mobiusloop
 
-Once installed, create a symbolic link for the `mobiusloop` command. First locate your ruby executable path:
+Once installed, create a symbolic link for the `mobius` command. First locate your ruby executable path:
 
     $ gem env
 
 Look for the value of `EXECUTABLE DIRECTORY`, something like `/usr/local/Cellar/ruby/2.2.3/bin/`.
 Then create a symbolic link:
 
-    $ ln -s </path/to/executable/directory/mobiusloop /usr/local/bin/mobiusloop
+    $ ln -s /path/to/executable/directory/mobius /usr/local/bin/mobius
 
-**TODO:** Find a way to create symbolic link as part of gem install to remove this manual step
+**TODO:** Simplify to find a way to create symbolic link as part of gem install
 
 
-## adding mobiusloop to your app
+## adding mobius to your app
 
 To create and run your own goals, let's start with a working example and modify it.
 
-Change to the root directory of your app and run `mobiusloop`:
+Change to the root directory of your app and run `mobius`:
+
+    $ cd product_root_directory
+    $ mobius
+
+You get feedback that `mobius` is not initialized. So let's do that:
+
+    $ mobius --init
+
+`mobius` creates a `goals/` directory and put some files in there. Let's run it again:
+
+    $ mobius
+
+You got feedback that `mobius` is running for your product!
 
-    $ cd product_home
-    $ mobiusloop
+If you get an error instead, attempt to debug the issue and [let us know](https://github.com/ryanshriver/mobiusloop-ruby/issues)
+so we can fix it.
 
-You get feedback that `mobiousloop` is not initialized. So let's do that:
+Now let's customize `mobius` for your needs.
 
-    $ mobiusloop --init
 
-`mobiusloop` just created a `goals/` directory and put some files in there. Let's run our example:
+# create your first goal
 
-    $ mobiusloop
+Mobius ships with a working goal to get you started.
 
-If all goes well, you get feedback that `mobiusloop` is running for your product! Now let's customize it for your needs.
+Open `goals/increase_readers.goal` in your favorite text editor,
+change the *baseline* or *target value*. Save and run `mobius` again. Notice changes in the progress?
 
+Change the *baseline* or *target dates* and run `mobius` again. See more changes? Getting the hang of it?
 
-## create your first .goal
+As you experiment you may notice the progress being displayed in green, yellow or red font color.
+In addition to the quantitative progress, `mobius` reports on whether you are *on track*. All this is configurable
+but more on that later.
 
-First, open `goals/increase_readers.goal` in a text editor, change the baseline or target value, save and run again.
-Did you notice changes in the progress and status? Change the baseline and target dates and try again. Getting the hang of it?
 
-Now let's pretend you have a product outcome to **improve response time** for your product from 4.5 seconds to 1 second.
+#### step 1: create .goal file
+
+Let's pretend you have a product outcome to **improve response time** for your product from 5 seconds to 1 second.
 Start by copying our working example:
 
-    $ cp goals/increase_readers.goal goals/improve_response_time.goal
+    $ cp goals/increase_readers.goal goals/improve_experience.goal
+
 
+#### step 2: create objectives and outcomes
 
-#### create objectives and outcomes
+Open `improve_experience.goal` in your text editor and make some changes:
 
-Open the new `improve_response_time.goal` in your text editor and make some changes:
+ 1. Update `Objective:` to reflect our new goal. How about `Improve our digital customer experience this year`
+ 1. Let's only start with one `Outcome`, so delete from `Outcome: Increase Published Articles by 25%` to the end of the file
+ 1. Now update your `Outcome:` keeping it short and sweet. How about `Improve Response Time`
 
- - Update `Objective:` to reflect our new goal. How about <i>Improve our digital customer experience this year</i>.
- - Let's only start with one `Outcome`, so delete from `Outcome: Increase Published Articles by 25%` to the end of the file
- - Now update your `Outcome:` keeping it short and sweet. Something like <i>Improve Response Time</i>
+When done it should look like this:
 
-Now save the file and run again:
+```
+Objective: Improve our digital customer experience this year
 
-    $ mobiusloop
+ Outcome: Improve Response Time
+    Given a baseline of 500000 "readers" on "Oct 1, 2016"
+    And a target of 1000000 "readers" by "Oct 1, 2017"
+    Then measure progress with "Total Readers Scale"
+```
 
-This runs all the `.goal` files to `goals/` folder. We can just run our new one with this command:
+Save your new goal and run `mobuis` again. Notice that `mobius` runs all the `.goal` files in the `goals/` folder by default.
+We can just run our new one with this command:
 
-    $ mobiusloop goals/improve_response_time.goal
+    $ mobius goals/improve_experience.goal
 
-We don't need the example anymore, so let's remove it:
+Since we don't need the example anymore, let's remove it:
 
     $ rm goals/increase_readers.goal
 
 
-#### define baselines and targets
+#### step 3: define baselines and targets
 
-Open `improve_response_time.goal` again and let's update the baselines and targets.
-Let's pretend as of October 1, 2015 your app's home page takes 5 seconds to load. That's your baseline. Make a change:
+Let's pretend as of October 1, 2016 your app's home page takes 5 seconds to load. That's your baseline.
+Since your product owner has requested *sub-second response time*, that's your target.
 
- - In the row starting with `Given`, change 50000 to 5 and "readers" to "seconds"
+Open `improve_experience.goal` in your text editor and make some changes:
 
-Your product owner has said <i>sub-second</i> is their goal. That's your target. Make another change:
+1. In the row starting with `Given`, change `50000` to `5` and `readers` to `seconds`
+1. In the row starting with `And`, change `1000000` to `1` and `readers` to `second`
 
- - In the row starting with `And`, change 1000000 to 1 and "readers" to "second"
+When done it should look like this:
 
-Now save the file and run again:
+```
+Objective: Improve our digital customer experience this year
 
-    $ mobiusloop
+ Outcome: Improve Response Time
+    Given a baseline of 5 "seconds" on "Oct 1, 2016"
+    And a target of 1 "second" by "Oct 1, 2017"
+    Then measure progress with "Total Readers Scale"
+```
 
-This works, but we have 820,000 seconds! That's not right, so let's fix it.
+Now save the file and run `mobius` again.
 
+This works, but we have *820,000 seconds!* That's not right, so let's fix it.
 
-#### define scales
 
-Open `improve_response_time.goal` again and let's change the scale to record response times, not total readers.
+#### step 4: define scales
 
- - In the row starting with `When`, change "Total Readers Scale" to "Page Response Scale"
+Open `improve_experience.goal` in your text editor and make some changes:
 
-Now save the file and run again.
+1. In the row starting with `When`, change "Total Readers Scale" to "Page Response Scale"
 
-    $ mobiusloop
+When done it should look like this:
 
-Wow, much better! The "Page Response Scale" requested google.com and compared the response time to your target.
+```
+Objective: Improve our digital customer experience this year
 
-How did you do? Did you hit the target?
+ Outcome: Improve Response Time
+    Given a baseline of 5 "seconds" on "Oct 1, 2016"
+    And a target of 1 "second" by "Oct 1, 2017"
+    Then measure progress with "Page Response Scale"
+```
 
+Now save the file and run `mobius` again.
 
-## developing with mobiusloop
+Wow, much better! The *Page Response Scale* generated a request to [google.com](http://google.com) and compared the
+response time to your target of 1 second. It reported what percentage progress you had made to your
+target in your scheduled time. The color text indicates whether you are on track or not.
 
-Hopefully by now you're getting the hang of `mobiusloop`. During development there are three basic steps:
+Hopefully by now you know how to edit a `.goal` file with confidence and run them to report
+progress towards your objectives and outcomes. But unless all of your goals are related to page
+response time, you'll need to customize `mobius` to meet your needs.
 
 
-#### step 1: create a new .goal file in the goals/ directory
+# mobius development guide
 
-You can copy an example or start from scratch. When done, do a dry run to ensure your syntax is valid:
+Customizing `mobius` for your product is a 3 step process:
 
-    $ mobiusloop goals/your_objective.goal --dry-run
 
-Replacing `your_objective.goal` with your filename. If there's any syntax problems, fix them and run again until you get a clean run.
+#### step 1: create a new .goal file in the goals/ directory
 
+We recommend copying a working example and modifying to meet your needs. For the .goal filename, we recommend naming it
+after your objective or problem statement. Something like this:
 
-#### step 2: optionally create a step definition
+    $ cp goals/increase_readers.goal goals/improve_quality.goal
 
-`mobiusloop` ships with one step definition `goals/step_definitions/mobius_steps.rb`. If you write your objectives,
-problems, outcomes and key results in the format above there's no need to create one. However if you want to create your own
-format, you will need to create a custom step definition. To verify, run:
+Add your objectives, outcomes and the correct target and baseline values. When done, do a *dry run*:
 
-    $ mobiusloop goals/your_objective.goal
+    $ mobius goals/improve_quality.goal --dry-run
 
-If `mobiusloop` cannot find a matching step definition for your `.goal` file, it will tell you the step definition to create.
-Copy and paste this into a new file `your_name_steps.rb` and save it to the `goals/step_definitions` folder. For more
-info on step definitions, see [Cucumber's reference](https://cucumber.io/docs/reference#step-definitions).
+Dry runs valid the `.goal` syntax is correct without actually running the scales that measure progress. Ensure your
+syntax is valid before moving on.
 
 
 #### step 3: create a new Scale
 
-Create a new Ruby class to perform the measurement. For example, if your .`goal` file contains "My Custom Scale", the Ruby class would be:
+Currently the only way to create a custom scale is to write some Ruby code. Specifically you must create a new Ruby class
+that extends the `Scale` class and implements a `measure` method. For example, if your .`goal` file contains
+"My Custom Scale", the Ruby class would be:
 
 ```Ruby
 require 'mobiusloop/scale'
@@ -281,51 +322,72 @@ class MyCustomScale < Scale
 
 end
 ```
-This code lives in `my_custom.scale.rb`.
-Replace the line `total = fetch_your_total` with your custom logic.
-The last line `Measure.new(total)` returns a new measure.
+This class is saved to `goals/step_definitions/my_custom.scale.rb`. The line `total = fetch_your_total` would be replaced
+with your custom logic. The last line `Measure.new(total)` returns a new measure, as required by all Scales.
 
-We recommend writing unit tests around any custom scales you create to ensure they work as expected before integrating with `mobiusloop`
+We recommend writing unit tests around any custom scales you create to ensure they work as expected before integrating with `mobius`.
 
-To run a single `.goal`, try this:
+TODO: Add methods to write custom Scales without writing Ruby. Pre-ship a few common ones.
 
-    $ mobiusloop goals/your_objective.goal
 
-Where `your_objective.goal` is the name of your custom goal. You can run all the `.goal` files in `/goals` folder with this:
+#### step 3: configure mobius
 
-    $ mobiusloop
+Certain features of `mobius` are configurable in the `goals/support/config.yml` file. Specifically:
 
+```YAML
+measures:
+  save: false
+```
+Setting this to `true` records each `mobius` run's progress in a small `.json` file inside the `goals/measures` directory.
+The name of the file is the timestamp of when it was run. If you would like to report on trending
+progress of your objectives and outcomes over time, you incorporate these values.
 
-## advanced features
+TODO: Identify an relatively easy method to use these to report trending
 
-Because `mobiusloop` is an extension of [Cucumber](http://cucumber.io), there are many features in Cucumber that also
-exist in `mobiusloop`. A few examples:
 
-**Tags** - Use tags to create logical groups of Objectives, Problems, Outcomes or Key Results that you want run together.
-For example, adding `@mytag` to the line immediately above a definition and running it with:
+```YAML
+progress:
+  green_threshold: 10%
+  red_threshold: 30%
+```
+`mobius` reports progress in green, yellow or red font to indicate whether you are on track to hit your target by the
+target date. This is configurable with the values `green_threshold` and `red_threshold`.
 
-    $ mobiusloop --tags @mytag
+It is easiest to explain this with a picture:
 
-Will only run those Objectives, Problems, Outcomes or Key Results associated with that tag.
+TODO: Picture of progress with thresholds
 
-**Reports** - By default `mobiusloop` outputs the results to the command line. But you can also output reports in HTML,
-JSON or other formats. See [Cucumber reports](https://cucumber.io/docs/reference#reports) for more details.
 
+## advanced features
 
-## Testing
+Because `mobius` is an extension of [Cucumber](http://cucumber.io), there are many features in Cucumber that also
+exist in `mobius`. A few examples:
 
-`mobiusloop` is built using a test-first approach. We're proud of our tests, but we're always looking to add more.
-If you downloaded the source code to `/workspace/mobiusloop-ruby`, you can run the tests using this command from the source code folder:
+**Tags** - Use tags to create logical groups of Objectives, Problems, Outcomes or Key Results that you want run together.
+For example, add `@performance` to the line immediately above a definition:
+
+```ruby
+@performance
+Problem: Slow app response times are causing us to lose customers
 
-    $ rake spec
+```
+Then run with this:
+
+    $ mobius --tags @performance
 
+Only those definitions with the @performance tag are run.
 
-## Report Defects
 
-See a missing test or found a defect? [Let us know](https://github.com/ryanshriver/mobius/issues) by creating a new issue.
+## tests
+
+`mobius` is built using a test-first approach. We're proud of our tests, but we're always looking to add more.
+If you downloaded the source code to `/workspace/mobiusloop-ruby`, you can run the tests using this command from the source code folder:
 
+    $ rspec spec/mobiusloop/
 
-## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/mobius.
+## further reading
 
+I have personally found [The Cucumber Book](https://pragprog.com/book/hwcuc/the-cucumber-book) a great reference and
+ worthy of purchase if you would like to get the most of out `mobius`.
+ [Cucumber.io](http://cucumber.io) is also a reference I use.