TDD and other technical practices (exemplified by the Software Craftsmanship movement) are great for validating the correctness and quality of the code, but how do we establish the validity and quality of running software for its intended use? (No, I don’t believe ATDD solves that problem. I’ll dive into the differences in a bit).

Outcome Driven Software (ODS) represents a new way to create software. In short, it is a way to make software by first creating the demonstrative outcomes that will prove validity, then using those outcomes to drive the creation of the functional systems to support them.

Part process, part technique – ODS is still a journey, not a destination. My hope is that others can contribute to its refinement and evolution, as well as the production of tooling (similar to xUnit frameworks) that aid in the process.

Change Your Perspective: Software Is Massless

Before diving into the practical application, there are a few key concepts and insights I want to run by you. Much of this I have not seen mentioned elsewhere, if you know of other sources or pioneers of the past who have been here before, please let me know.

The first thing may seems obvious, but is not at all reflected in the habits of modern software development: software is what runs on hardware when it is used by its users. Please read that one more time.

It’s not about your code, your development process, your tests, your continuous integration or deployment, your build process, your stories, your fixtures, your methodology, your tools, your IDE or any of that stuff far removed from what it actually is and what’s really important and that’s those human beings sitting at the other end who use and live through what is actually your software.

I use the mantra “Software Is Massless” as a reminder that it’s electrons running through the CPU and I/O activity and impulses from input devices and to display devices – all being exercised by, or at the bequest of, users aka human beings. And what those humans want more than anything else from your software is positive emotional outcomes. They want to feel good about your software and they want to feel good knowing they got what they wanted out of your software.

Beyond validity, ODS is also designed to improve the quality of outcomes – moving beyond acceptable or satisfactory and instead delighting and exceeding expectations. Ultimately, the quality of software depends on the creativity and empathy of those involved in creating it. However, ODS structures the process to allow this to happen more freely and as an upfront requisite before system design.

ODS is complimentary to core XP technical practices, though it fundamentally changes the act of coding and largely reduces the amount of TDD required.

ODS is a replacement for Acceptance Test Driven Development (and other derivatives such as BDD and Specification by Example). The intense focus on stakeholder conversations and collaboration from these techniques is directly applicable. However, the practices are different in two regards:

1. ODS creates running software instead of separate fixtures or artifacts that only run in the development shop and are not part of the software as it is used.
2. At the start, ODS explicitly avoids system design and focuses only on outcomes. In the “Given, When, Then” parlance of BDD, ODS starts by creating “Then” to the exclusion of “Given” and “When” which are created from “Then”.

Understanding the Difference between Functional and Demonstrative Parts of Technology

One way to think about any technology is as a progression from inputs to outputs and then from outputs to outcomes.

Realize though that the boxes and arrows are somewhat misleading because what we actually create are the arrows not the boxes:

The progression from input to output occurs through a functional mechanism (or functional system if you like). This translates quite easily into code, for example consider the following:

function add(a, b) { return a + b }

Given an input of 1 and 2, the output will be 3. The “rightness” of input/output relationships is usually expressed via “test”:

assert.equal(3, add(1,2))

Understanding the progression from output to outcome can be more difficult. This is because the outcome exists at the intersection between the running software and its user(s). Meaning outcome can only be understood as running software, not as code. Expanding the add example:

function add(a, b) { return a+b }
var prompt = require('./console-prompt')
prompt(['First number:', 'Second number:'], function(addends){
   var a = addends[0], b = addends[1]
   console.log(a + ' + ' + b + ' = ' + add(a,b))
})

it will yield the following when run:

C:\node\ods>node add.js
First number: 1
Second number: 2
1 + 2 = 3

Given the simplicity of this example, we can consider the entirity of the three lines:

First number: 1
Second number: 2
1 + 2 = 3

to be the demonstrated outcome. But to simplify for a momment, let’s just look at the last line presented to the user:

1 + 2 = 3

as the outcome. The demonstrative system (meaning the part of the software that produces this output to the console)  produces this ‘artifact’ to provide validation of the outcome. This artifact of outcome can be judged qualitatively. It could have been:

Your answer is 3

Or as is too often the case today, the output could also have been provided directly (technically the REPL facilities are being leveraged to deliver the outcome via an on-screen presentation of the number) with no attempt to consider outcome:

3

In this very simple example as presented, this may be fine. But imagine the potential frustration if the originally provided addends were not visible and the user had to re-run the software. The important thing is the conversation and collaboration to discover the best demonstration the outcome. The ‘right’ thing to do is bound to context and focused conversation with users and stakeholders on the outcome reveals all the subtle nuances and details.

It is also very critical to realize that the discussion about outcome can occur without the functional system. This fact is exploited by ODS: outcomes are discussed and determined early on and the functional system is only built after the purpose of the software is understood.

[If you’re wondering about more complex software, ODS can be applied at multiple levels. Software systems, and system here includes input all the way through outcome, can have nested sub-systems.  For example, the prompt for addend can be thought of as a sub-system. This example is so simple there is hardly any difference between the output and outcome other than display of the number as it is produced.]

The Outcome-First Process

In the add example, as I mentioned, because it so simple we can consider the outcome as the total record of supplying and adding the numbers. So let’s assume that for the process of adding the number 1 and 2, we work with the user to come up with the following:

C:\node\ods-add>node addition.js
First number:  1
Second number: 2
1 + 2 = 3

This is implemented very simply as:

var colors = require('colors')
console.log('First number:  1')
console.log('Second number: 2')
console.log('1 + 2 = 3'.green)

Notice that this is a fully runnable, complete software. The user is not being asked in the abstract or conceptual about what they want. No tables or fixtures are being created. They are evaluating real software in its real target environment. The delivery and deployment can also be exercised.

It just only covers the specified example (adding the numbers 1 and 2). Only the outcome needs to be produced, allowing rapid iteration and interaction with the user to find the best possible outcome.

Once there is agreement on the outcome, the next step is to pin this outcome and set up a test that will check that the same outcome is being produced. This will allow making changes that allow us to safely move backwards in creating the rest of the software.

Just like with xUnit for TDD, some basic tooling can help with this process. ODS utilizes tooling that can do photocopy testing. Photocopy testing is the process of capturing the representation of the outcome as an agreed upon ‘standard’ and then being able to compare subsequent outcome production against the captured ‘standard’.

For this CLI example, I’ve created a simple utility that can both pin the outcome and test subsequent executions against that tooling. My main focus is on web development and I have blueprint, a web-based ODS tool for web application development. The process works fine for command line apps as well. It just goes to show how much detail is exposed by focusing on running software versus developing code.

C:\node\ods-add>node test.js addition.js -p
pinned addition.js outcome to addition.outcome.txt
saved outcome:
First number:  1
Second number: 2
1 + 2 = 3

With the –p pin option, it saves the stdout output to a text file. Without the pin option, the program tests the outcome against the expected result:

C:\node\ods-add>node test.js addition.js
First number:  1
Second number: 2
1 + 2 = 3
----------
passed
----------

Combining this with watch enables a continuous real-time feedback mechanism. When the program is modified (and the file saved) we will know immediately if we are no longer producing the agreed upon outcome, for example if we change the last line to:

console.log('1 + 2 = 4'.green)

we see:

C:\node\ods-add>..\watch\watch node test.js addition.js
First number:  1
Second number: 2
1 + 2 = 3
----------
passed
----------

First number:  1
Second number: 2
1 + 2 = 3
----------
passed
----------

failed!

Expected>>First number:  1
Second number: 2
1 + 2 = 3
<<
Actual  >>First number:  1
Second number: 2
1 + 2 = 4
<<
----------

Working backwards is essentially a refactoring effort from static to dynamic input. In ODS, the first step is to extract the output from the outcome. In practical terms, that means creating a view and a model (not showing the first three lines):

console.log('%s = %s'.green, '1 + 2', '3')

One difference for me in working backwards from a fully functional outcome, versus building up an output, is that I see the totality of what is being described. So I’ve decided to isolate the addends as a unit, rather than discrete numbers.

var addends = [1, 2]
,  sum = 3
console.log('%s = %s'.green, addends.join(' + '), sum)

With the simplicity of this example, we’ve not only isolated the output (sum), but the input as well (addends).  Now the functional mechanism can be added:

var addends = [1, 2]
,  sum = addends[0] + addends[1]
console.log('%s = %s'.green, addends.join(' + '), sum)

You can take this in many directions. You could create an add method:

function add(a,b) { return a+b }
var addends = [1, 2]
,  sum = add(addends[0], addends[1])
console.log('%s = %s'.green, addends.join(' + '), sum)

Or maybe a class:

var addition = {
 ,  addends: [1,2]
 ,  sum: 3
 ,  toString: function() {
       return util.format('%s = %s'.green,
       this.addends.join(' + '), this.sum)}

}

console.log('%s'.green, addition)

Or an event emitter/service approach:

calculator.on('sum', function(addition) {
  console.log(formatter.render(addition))
})

ODS provides focus on and awareness of code design. Various designs can be tried and discarded at low cost.

Keeping this example simple, the last step is to implement the input mechanism:

var colors = require('colors')

var prompt = function(prompts, cb) {
  console.log(prompts[0] + '1')
  console.log(prompts[1] + '2')
  cb([1, 2])
}

prompt(['First number:  ', 'Second number: '], function(addends) {
  var sum = addends[0] + addends[1]
  console.log('%s = %s'.green, addends.join(' + '), sum)
})

Now the ‘real’ library can be swapped in (but…):

var colors = require('colors')
,  prompt = require('./console-prompt')

prompt(['First number:  ', 'Second number: '], function(addends) {
  var sum = addends[0] + addends[1]
  console.log('%s = %s'.green, addends.join(' + '), sum)
})

But, the test now needs to be modify to provide the inputs (full code on gitub):

var answers = ['1','2']
child.stdout.on('data', function(data){
  buf.push(data)
  process.stdout.write(data)
  var answer = answers.shift()
  if(answer) { writeLine(answer) }
})

And the test passes:

C:\node\ods-add>node test.js addition.js
First number:  1
Second number: 2
1 + 2 = 3
----------
passed
----------

Of course, there is the working software:

C:\node\ods-add>node addition.js
First number:  34
Second number: 15
34 + 15 = 49

Reviewing the Steps of the ODS Outcome-First Process

Reviewing, here are the foundational steps:

1. Establish an agreed upon outcome (go big and create delight!)
2. Pin the outcome via test
3. Extract the inputs into the outcome
4. Outcome inputs are also the (functional) system outputs
5. Work backwards through the functional system to the inputs

Project is available on github here.

You can also check out an Event Registration example I did about a year ago here.

http://www.kickstarter.com/projects/242604490/irish-language-hunt

Thanks again to everyone who helped out!

I need your help.

This last summer a new non-profit, Language Hunters (LH), was formed by my friend Willem Larsen who asked me to sit on the board. LH is one of those big, hairy, audacious goal kind of non-profits that not only wants to change the world, but I believe can change the world.

See, LH uses a game play technique to teach language that’s nothing like those dull, boring language courses most of us sat through in high school. A year (or more) of focus on vocabulary and grammar, yet how many of us would now feel comfortable having a conversation with a native speaker or even taking care of basic needs when travelling abroad?

What Willem and his colleagues figured out is that mimicry and copying is how people learn languages. Think about it, did any of us take English lessons as babies and toddlers? Now imagine that same natural learning occurring at much faster rate because, well, we’re not babies anymore.  The best part is that we don’t have to work at it, or memorize anything, we just play along.

LH’s goal is to create a multilingual world where kids (and adults!) can routinely speak 20 or more languages. And not just French, Spanish and German – but indigenous and heritage languages which are currently in a state of crisis and are at risk of being lost forever!

To accomplish this, LH has to both develop language specific programs and services as well as create opportunities to deliver those programs and services. LH has done that in past through workshops, often with specific indigenous communities. LH is also looking to expand programming in schools in 2012.

What I need from you today is to help fund a project to expand the reach of LH through the use of game videos that can be used by anyone around the world who has access to the internet. There is now a project on Kickstarter to create a video game to learn the endangered Irish language (Gaeilge).

LH has already spent over 400 person-hours to create a sample of the first “set” (over 20 sample videos!) and this project would allow them to revamp those videos, create the next 3 sets along with transcripts and supporting materials. Head on over, check those out and learn some Irish.

Then, I need you to do two things:

• Make a pledge. Even if it’s only $1 it helps by elevating the project’s popularity and draws more attention and pledges! Of course, I’d love for you to pledge more to help us reach our goal of $3,500 (already over $1,000 has been pledged after only six days!). Kickerstarter even has easy integration with Amazon, so if you’ve already got an account you don’t even need to both with typing all that credit card info!
• Tell everyone you know about it.  Just a few clicks will spread the word. You can use one of the Share links below to link to this page, or Share from the project page on Kickstarter.  Seriously, how easy is that?

I appreciate your support and thank you in advance,

- Marty

Software Is Massless

Our approach to software creation is largely based on our experience of constructing and interacting with physical objects. Software is massless and moves at the speed of light, so why do we delay our high aspirations for ecstatic outcomes and allow them to fade as we labor on structure, mechanisms and infrastructure? The time has come to break these self-inflicted chains that hold us back from our true potential as wizards of creation.

Lifting the veil, I’ll show you how to reconnect with the power to empathize and collaborate directly with customers and users to create the most important, meaningful parts of your software right from start instead of falling down the rat hole of system design. Then see how this inversion of fulfillment simplifies and minimizes the creation of the system necessary to support the outcomes that have already been created.

We should set aside “the system” and “thinking” entirely. Instead, focus on a moment in time after the system has already been used and ask what is required to bring about positive emotional outcomes for the participants. This is a different type of labor, one Seth Godin in his book Linchpin describes as “emotional labor” (read about or read on Seth’s blog or one-minute video). I refer to it more generally as just empathy.

It is effective because it allows us to directly envision what will delight and fulfill the emotional needs and wants that truly drive human behavior and satisfaction. It also liberates us creatively because we temporarily remove any focus on the constraints of what the mind believes is possible in the construction of any system.

If we start by this process of “empathetic visioning”, then the subsequent use of systems thinking is done with a clear knowledge of the set of outcomes that must be produced to support the vision. In my experience thus far (it forms the basis of Feature TDD), this reduces system problems to either trivial concerns or makes them well suited to solving by traditional analytical creativity.

^[1] From Karl Popper, I was recently introduced to the concept by my father who sent me a link to Gaurav Mishra’s interesting post on applying clocks or cloud to social media.

This leads me to two possible (and not mutually exclusive) conclusions:

1. ‘Customer pulls value’ is not a principal, but rather is itself a practice (a technique to be used in certain contexts) used in support of a principal such as “customer co-creation and collaboration” (in which both push and pull occur).
2. We recognize empathy as the practice that supports the ‘customer pulls value’ principal, as it can be proactively initiated while fully maintaining receptivity to pulling.

From wikipedia:

Empathy is the capacity to recognize and, to some extent, share feelings (such as sadness or happiness) that are being experienced by another semi-sentient being. Someone may need to have a certain amount of empathy before they are able to feel compassion.

Implement the Functional Behavior

The Existing Event Spec

Let’s look again at the main part of event-spec.js:

vows.describe('Event').addBatch({
  'An Event': {
    'when asked for guests': {
      topic: function () {
        Event.getGuests(this.callback);
      },
      'should return the standard guests':
        function (err, guests) {
          assert.deepEqual (guests,
            ['Bob', 'Sally', 'Tim', 'Joe']);
        }
    },
  'when registering Bob': {
      topic: function() {
        Event.register('Bob', this.callback);
      },
      'should return Bob':
        function (err, guest){
          assert.equal(guest, 'Bob');
        }
     }
  }
}

Adding Event Registration

What I want to do is register the four standard guests, then execute the guest list test to see that those four guests are returned. Vows executes sibling contexts in parallel, so I need to either use separate batches or use a sub-context. I messed around with both, and for now I decided to go with two batches. The basic structure will be:

vows.describe('An Event')
.addBatch({
  'when guests register' : //register each guests
})
.addBatch({
  'when asked for guest list': //get confirmation list
}).export(module);

For the first addBatch (register), I’ll take the current test and move it into that block:

.addBatch({
  'when guests register' : {
    'like Bob': {
      topic: function() {
        Event.register('Bob', this.callback);
      },
      'should return Bob': function (err, guest) {
        assert.equal(guest, 'Bob');
      }
    }
  }
}

This would get repetitive for multiple register calls, so I’ll refactor out the context into a method:

.addBatch({
  'when guests register' : {
    'like Bob': registerGuest()
  }
}
...
function registerGuest() {
  return {
    topic: function() {
      Event.register('Bob', this.callback);
    },
    'should confirm Bob': function (err, guest) {
      assert.equal(guest, 'Bob');
    }
  };
}

Which can be parameterized to:

'like Bob': registerGuest('Bob')
...
function registerGuest(guest) {
  var context = {};
  context.topic = function() {
      Event.register(guest, this.callback);
  };
  context['should confirm ' + guest] = function (err,
    response) {
        assert.equal(response, guest);
    }
  return context;
}

Adding in each of the four expected guests makes the 'when guests register' context:

'when guests register' : {
  'like Bob': registerGuest('Bob'),
  'like Sally': registerGuest('Sally'),
  'like Tim': registerGuest('Tim'),
  'like Joe': registerGuest('Joe')
}

I don’t like the duplication on each line, nor the overall duplication for each guest. I can clean this up by introducing this method:

function registerGuests(){
  var context = {};
  for(arg in arguments){
    var guest = arguments[arg];
    context['like ' + guest] = registerGuest(guest);
  }
  return context;
}

Here is the entire event test suite file at this point:

var vows = require('vows'),
assert = require('assert')

var Event = require('../lib/event').getEvent();

vows.describe('An Event')
.addBatch({
  'when guests register' :
    registerGuests('Bob', 'Sally', 'Tim', 'Joe')
}).addBatch({
  'when asked for guests': {
    topic: function () {
      Event.getGuests(this.callback);
    },
    'should return the standard guests':
      function (err, guests) {
        assert.deepEqual (guests,
          ['Bob', 'Sally', 'Tim', 'Joe']);
    }
  },
}).export(module);

function registerGuests() {
  var context = {};
  for(arg in arguments) {
    var guest = arguments[arg];
    context['like ' + guest] = registerGuest(guest);
  }
  return context;
}

function registerGuest(guest) {
  var context = {};
  context.topic = function() {
    Event.register(guest, this.callback);
  };
  context['should confirm ' + guest] = function (err,
    response) {
      assert.equal(response, guest);
  }
  return context;
}

The corresponding code in event.js is:

exports.getEvent = function () {

  return new Event();

  function Event() {
    var guests = [];
    this.getGuests = function(callback) {
      callback(null, guests);
    };
    this.register = function(guest, callback) {
      guests.push(guest)
      callback(null, guests[guests.indexOf(guest)]);
    };
  }
}

The Data Store Functionality

Yes, this is just a simple in-memory array based solution. I’ve done the simplest possible thing for my purposes right now. It is appealing to be able to validate the system with an in-memory data storage structure, then implement a more appropriate data store. Either way, what I want you to notice is that the technique puts an emphasis on minimizing the functional aspect while providing a design that has cleanly decoupled the actual data store implementation.

For those looking for more on data with node, there are (multiple) open-source modules for CouchDb (see here for more), Mongo, SqlLite and others; plus some light-weight keyed value stores like node-dirty and nStore (also, check this post by Chris Strom where he does both a CouchDB and node-dirty implementation).

Some Loose Ends

I still need that test for registering with a missing name:

'with missing name' : {
  topic: function() {
    theEvent.register('', this.callback);
  },
  'should return an error': function (err, ignore) {
    assert.isNotNull(err);
  }
},

Which I can extract and follow a similar pattern as the register tests in order to expand to multiple ‘bad’ inputs:

'with missing name' : noMissingNames({
  'empty string': '',
  'null': null,
  'white space': '    ',
  'undefined': undefined}),
...
function noMissingNames(missingNames) {
  var context = {};
  for(label in missingNames) {
    context[label] = noMissingName(missingNames[label]);
  }
  return context;
}

function noMissingName(missingName) {
  return {
    topic: function() {
      Event.register(missingName, this.callback);
    },
    'should return an error': function (err, ignore) {
      assert.isNotNull(err);
    }
  };
}

And now that I’m actually using the err parameter for register, I’ll add a check in my registerGuest method to make sure no error is returned on a good confirmation:

function registerGuest(guest) {
  var context = {};
  context.topic = function() {
    Event.register(guest, this.callback);
  };
  context['should not return any errors'] =
    function (err, ignore) {
      assert.isNull(err);
  };
  context['should confirm ' + guest] = function (err,
    response) {
      assert.equal(response, guest);
  }
  return context;
}

The guard clause in event for missing names is:

this.register = function(guest, callback) {
  if(!(guest) || (/^\s*$/).test(guest)) {
    callback ('Name must be provided');
    return;
  }
...

I also added tests and code to make supplying no callback parameter safe (check those out on github if you’re interested).

The Whole Test Suite

Running the event-spec.js test suite now yields:

$ vows --spec event-spec.js

♢ An Event

  when guests register like Bob
    ✓ should not return any errors
    ✓ should confirm Bob
  when guests register like Sally
    ✓ should not return any errors
    ✓ should confirm Sally
  when guests register like Tim
    ✓ should not return any errors
    ✓ should confirm Tim
  when guests register like Joe
    ✓ should not return any errors
    ✓ should confirm Joe
  with missing name empty string
    ✓ should return an error
  with missing name null
    ✓ should return an error
  with missing name white space
    ✓ should return an error
  with missing name undefined
    ✓ should return an error
  when asked for guests
    ✓ should return the standard guests
  No callback provided on getGuests
    ✓ is safe
  No callback provided on register
    ✓ is safe

✓ OK » 15 honored (0.023s)

Create the Functional User Interface

The Registration Templates

I’ll use the same initial technique to create the jade template for registering as I did for the initial registration confirmations:

h1 Register for Larry's Event
form(action: '/guests', method: 'post')
  fieldset
    p
      label(for="name") Name:
      input(name: 'name')
    p
      input(type: 'submit', value="register")

Which renders as:

I create the static, literal output and can again pin it with a test:

'Registration form': getContext('registration',
  function () {
    client.get('/registration', this.callback);
  })

And add the get method to the server code:

app.get('/registration', function (request, response) {
  Render(response, 'signupform');
});

I also need to create a template for the error condition, which is just a variation in the signup form (versus a separate response page):

h1 Register for Larry's Event
form(action: '/guests', method: 'post')
  fieldset
    p#error(style="color: red")
      | Name must be provided
    p
      label(for="name") Name:
      input(name: 'name')
    p
    input(type: 'submit', value="register")

I’ll create another literal template spec:

'Registration form with error': getContext(
  'registration-error', function () {
    client.get('/registration-error', this.callback);
  })

And until these two templates get united via refactor, I’ll create a separate get in the server code:

app.get('/registration-error', function (request,
  response) {
    Render(response, 'registration-error');
});

Now I’ll modify the registration.jade template:

h1 Register for Larry's Event
form(action: '/guests', method: 'post')
  fieldset
    - if (locals.error)
      p#error(style="color: red")= error
    p
      label(for="name") Name:
      input(name: 'name')
    p
      input(type: 'submit', value="register")

The registration-error get can now use the same template and pass in the error:

app.get('/registration-error', function (request,
  response) {
    Render(response, 'registration',
      {error: 'Name must be provided'});
});

The spec tests pass. Now I’ll refactor out a renderRegistration method for both gets:

app.get('/registration', function (request, response) {
  renderRegistration(response, 'registration');
});

app.get('/registration-error', function (request,
  response) {
    renderRegistration(response, 'registration',
      'Name must be provided');
});

function renderRegistration(error) {
  var locals = (error) ? {error: error} : null;
  render(response, 'registration', locals);
}

Thoughts on Application Context

The registration-error ‘get’ can technically be deleted once we get the registration functionality in place. However, I’d like to find a way to preserve the standard tests as a different application context, but that will need to be a problem for another day.

Test-Drive the Integration to the Finish Line

Automated Browser Tests
I’ll bring in one more testing tool to drive our final integration steps. Meet zombie, the ‘Insanely fast, headless full-stack testing using Node.js’. I’ll use zombie in the vows tests to simulate the user browser activity.

There are two tests I’ll write, one for a successful registration, and the other for a missing name registeration:

var vows = require('vows'),
    assert = require('assert'),
    zombie = require('Zombie');

vows.describe('Event Registration').addBatch({
  'Register Guest' : {
    topic: function () {
      var callback = this.callback;
      zombie.visit('http://127.0.0.1:3003/registration',
        function (err, browser, status) {
          browser.fill('name', 'Pablo');
          browser.pressButton('register', callback);
      });
    },
    'browser should respond without error': function (err,
      browser, status) {
        assert.isNull(err);
    },
    'and with http status 200': function (err, browser,
      status) {
        assert.equal(status, 200);
    },
    'and contain the confirmation': function (err, browser,
      status) {
        assert.notEqual(browser.html().indexOf(
          'Thanks for registering Pablo!'), -1);
    }
  },
  'Register with No Name' : {
    topic: function () {
      var callback = this.callback;
      zombie.visit('http://127.0.0.1:3003/registration',
        function (err, browser, status) {
          browser.fill('name', '');
          browser.pressButton('register', callback);
      });
    },
    'browser should respond without error': function (err,
        browser, status) {
          assert.isNull(err);
    },
    'and with http status 200': function (err,
      browser, status) {
        assert.equal(status, 200);
    },
    'and contain the confirmation': function (err,
    browser, status) {
        var error = browser.querySelector("#error");
        assert.ok(error);
        assert.equal(error.textContent,
          'Name must be provided')
    }
  }
}).export(module);

Now we can wire up the registration, here is the server code in its entirety:

express = require('express'),
connect = require('connect'),
app = express.createServer(
  express.bodyDecoder());
app.set('views', __dirname + '/views/');

var Event = require('./lib/event').getEvent();

app.get('/guests', function (request, response) {
  Event.getGuests(function(err, guests) {
    render(response, 'guests', {guests: guests});
  });
});

app.post('/guests', function (request, response) {
  console.log('name', request.param('name'));
  Event.register(request.param('name'),
    function(err, data) {
      if(err) {
        renderRegistration(response, err);
      } else {
        render(response, 'confirmation', {guest: data});
      }
    });
});

app.get('/registration', function (request, response) {
  renderRegistration(response);
});

function renderRegistration(response, error) {
  var locals = (error) ? {error: error} : null;
  render(response, 'registration', locals);
}

function render(response, template, locals) {
	var options = { layout: false };
	if(locals) { options.locals = locals; }
	response.render(template + '.jade', options);
}

app.listen(3003);
console.log("Listening on port 3003");

Final Thoughts

Again, the code is available in github.

The basic difference from traditional software development was to start with a literal projection of the confirmations that would show the customer and user they got what they wanted. From that I was able drive the functional part of the application by pulling the data and functionality out of the literal templates and into the application.

There are still some rough spots, and I am also relatively new to javascript, node.js and modern web design. My next goal, besides continuing to use the new technique, is to develop some tooling to help with some of the boiler-plate activities.

In the third post in my Neoagility series, I’ll take a step back up a level and look at some of the ramifications of doing software development in this manner.

• The functional aspect is the mechanism used to bring about a result
• The confirmational aspect is what lets the user know that their desires and goals for using the software have been met.

The key to Feature TDD is to build the confirmational aspect first, which then serves as the ‘test’ for the subsequently developed functional aspect. Here are the steps I’ll be using:

1. Capture vision and intent through literal confirmational representation
2. Pin output of #1 via test
3. Make vision templates data-driven
4. Extract data model and create functional stubs
5. Implement functional behavior
6. Use techniques #1 and #2 to create functional user interfaces
7. Link #6 to functional behavior created in #5

In the post, I’ll cover steps #1-#4.

This simple example is going to be focused on a very simple event registration web site for our hypothetical customer Larry. I’m going to be using node.js for this exercise. I have playing around with it for the past few months, and it has been a very compelling technology thus far.

Capture Vision and Intent

Conversation

The goal for this step is to work with the customers and users to agree upon a set of interfaces and indications that will demonstrate that their vision or intent has been satisfied by the system (you can also think about it as answering “what will will make them happy?”). This is very similar to Specification by Example or BDD, except that the focus is solely on the confirmational aspects of the features.

For more detailed specific techniques for engaging the customer, check out my post here, and also Gojko Adzic’s interesting new technique of effect-maps. A real conversation with Larry would expose a lot of in-depth contextual answers.

Right now, I want to show the end-to-end technique so I’m going to keep this extremely simple and say that Larry really just wants to see a list of names of those who have registered for his event.

Literal Templates

I’ll be using the templating engine jade to quickly work up the presentation. It’s format is fairly simple, and I like it because it can yield a visualization very simply and quickly. Here is the literal template for the guest list:

h1 Guest List for Larry's Event
ul#guests
  li Bob
  li Sally
  li Tim
  li Joe

And here is the node.js server-side code for rendering this (I’m also using express and connect, a web framework for even simpler application routing and server) :

express = require('express'),
connect = require('connect'),
app = express.createServer();
app.set('views', __dirname + '/views/');

app.get('/guests', function (request, response) {
  response.render('guests.jade',
          { layout: false, });
});

app.listen(3003);
console.log("Listening on port 3003");

This renders as:

I won’t be going any further than running on my local dev machine at this point, but with this simple, small fragment, there is enough to begin learning (by doing) about (continuous) deployment.

Also, with my tester hat on I notice that Larry probably wants to prevent empty names from showing on his list. For now, I’ll just record this observation.

Moving on to the next step I’ll focus on the guest who registers. Again, after deferring to Larry, I’ll assume we can  keep this very simple:

h1 You Are Registered for Larry's Event
p Thanks for registering Bob! We look forward to seeing you.

Another get method is added to the code and a Render method can be refactored out:

app.get('/guests', function (request, response) {
  Render(response, 'guests');
});

app.get('/guests/confirmation', function (request, response) {
  Render(response, 'confirmation');
});

function Render(response, template) {
	var options = { layout: false };
	response.render(template + '.jade', options);
}

The new method will soon be changed to app.post('/guests', but initially we want the resource to be directly accessible so the outcome is demonstrable (some of the tooling I’ll show later makes this step unnecessary). This renders:

At this point, these confirmation ‘tests’ have been validated by Larry, and we can consider that the output is now the ‘gold standard’ of captured intent and vision.

Pin the Standards with Tests

The output is pinned so that the next step of making the templates data-driven can be made with the confidence that the standard has not changed. Fixing the html output from jade is trivial from the command line:

$ jade guests.jade confirmation.jade
  create : guests.html
  create : confirmation.html

There are a number of node.js testing frameworks, I’m going to use Vows to write the tests. I rolled my own quick http-client module which is picked up at var client = require('./http-client'). There’s probably a good node module for this that I just haven’t found yet.

Here is the basic structure of the test, the client http response is compared against the spec standard:

topic: function () {
  client.get('/guests', this.callback);
},
'should return the standard':
  function (err, httpResponse) {
    fs.readFile('./html standards/guests.html', 'utf-8',
      function(err, standard) {
        assert.isNull(err);
        assert.equal(httpResponse.data, standard);
    });
  }

Adding both tests and refactoring out the common aspects leaves the initial test file as:

var vows = require('vows'),
assert = require('assert'),
fs = require('fs');

var client = require('./http-client');

vows.describe('Event Registration Confirmation')
  .addBatch({
    'Guest List Confirmation': getContext('guests',
      function () {
        client.get('/guests', this.callback);
      }),
    'Registration Confirmation': getContext('confirmation',
      function () {
        client.getPost('/guests', this.callback);
      })
  }).export(module);

function getContext(standard, httpGet) {
  return {
    topic: httpGet,
    'should return the standard': function (err,
      httpResponse) {
        fs.readFile('./html standards/' + standard + '.html',
          function(err, response) {
            assert.isNull(err);
            assert.equal(httpResponse.data, response);
      });
    }
  }
}

The signature of the registration confirmation is changed to be a post operation, and running the tests (the server app also needs to be running too) yields the following:

Marty.Nelson@Laptop-Mnelson7 ~/Larry's Event/tests
$ vows --spec confirmation_specs.js

♢ Event Registration Confirmation

  Registration Confirmation
    ✓ should return the standard
  Guest List Confirmation
    ✓ should return the standard

✓ OK » 2 honored (0.119s)

Data-Drive the Templates

With tests in place, the templates can be safely changed to be data driven. There are two parts to the change, the first is to pull the literal data values out of the templates and into the server code (passing them into the template):

app.get('/guests', function (request, response) {
  Render(response, 'guests',
    {guests: ['Bob', 'Sally', 'Tim', 'Joe']});
});

app.post('/guests', function (request, response) {
  Render(response, 'confirmation', {guest: 'Bob'});
});

function Render(response, template, locals) {
	var options = { layout: false };
	if(locals) { options.locals = locals; }
	response.render(template + '.jade', options);
}

And the second is to parameterize the jade templates:

h1 Guest List for Larry's Event
ul#guests
  - each guest in guests
    li= guest

and

h1 You Are Registered for Larry's Event
p
  | Thanks for registering #{guest}!
  | We look forward to seeing you.

The tests still pass (I’ve removed the more verbose –spec option):

$ vows specs.js
··

? OK » 2 honored (0.051s)

Functional Stub

Next, I’ll push the literal code into an Event stub. Because node.js code should be non-blocking, the calls into the Event follow the pattern of supplying a callback, and that callback (by convention) has the signature (err, data):

Event.getGuests(function(err, data) {
    if(err) { console.log('we got an error', err'); }
    console.log('return data:', data);

I’ll start by extracting it from the server get methods:

var Event = {};
Event.getGuests = function(callback) {
  callback(null, ['Bob', 'Sally', 'Tim', 'Joe']);
};
Event.register = function(name, callback) {
  callback(null, 'Bob');
};

app.get('/guests', function (request, response) {
  Event.getGuests(function(err, data) {
    Render(response, 'guests', {guests: data});
  });
});

app.post('/guests', function (request, response) {
  Event.register(request.param('name'), function(err, data) {
    Render(response, 'confirmation', {guest: data});
  });
});

Then I’ll move the Event code into another file (under the lib folder):

exports.getEvent = function () {

  return new Event();

  function Event() {
    this.getGuests = function(callback) {
      callback(null, ['Bob', 'Sally', 'Tim', 'Joe']);
    };
    this.register = function(name, callback) {
      callback(null, 'Bob');
    };
  }
}

And require it as a node module in the server code:

var Event  = require('./lib/event').getEvent();

Now I want to use traditional TDD to flush it out. Oddly, I need to backfill tests at the Event module level that are coming after the stub. Another approach would have been to build up the identical interface to what was extracted in the server code. After the first few cycles, the tests looks like:

var vows = require('vows'),
    assert = require('assert')

var Event = require('../lib/event').getEvent();
vows.describe('Event').addBatch({
  'An Event': {
    'when asked for guests': {
      topic: function () {
        Event.getGuests(this.callback);
      },
      'should return the standard guests':
        function (err, guests) {
          assert.deepEqual (guests,
            ['Bob', 'Sally', 'Tim', 'Joe']);
        }
    },
  'when registering Bob': {
      topic: function() {
        Event.register('Bob', this.callback);
      },
      'should return Bob':
        function (err, guest){
          assert.equal(guest, 'Bob');
        }
     }
  }
}).export(module);

Running these tests yields:

$ vows --spec event_specs.js

♢ Event

  An Event when asked for guests
    ✓ should return the standard guests
  An Event when registering Bob
    ✓ should return Bob

✓ OK » 2 honored (0.013s)

Next Steps

I’m well setup to  flush out the functional aspects of the Event class. In the next post, I’ll do this and then work my way back to the Registration interface to complete the applicaton.

You can view the code at github. If you know how to view history, the commit for the first part is labelled.

P.S. Thoughts on Tooling…

In doing a few of these templates, I created a web tool intended to be a rapid collaborative environment for this technique:

The output in the upper-right updates in real-time as the template is modified. The “save template” button saves the template to the project and also creates the static html ‘standard’ representation. The CSS area is not currently functional, but you can see how this be used to provide design aspects.

I have also been working on making these editors collaborative so that you could have multiple team members working up the confirmation feature (ideally with the customer or product owner) at the same time.

Keep in mind that currently, because it is traditional written after the functional part of the feature, the confirmational aspects may be missing or poorly implemented. Google does a pretty decent job on simple usability, so let’s look at Gmail for a visible example of the conformational versus functional aspect of features.

Sending an Email

When I send an email from GMail by clicking the send email button, I am exercising the functional aspect of sending an email. My button click causes browser code to execute and a call gets made to the server which uses SMTP to send that message to the recipient(s):

But how do I know it worked?

It can be helpful to think of confirmation as a contract for the software that answers this question. Actually reading the contents of the recipients inbox to validate the email was sent poses security and privacy issues. ‘Read Receipt’ type approaches also are not generally excepted social practices outside of some segments of the business world. So, the ‘contract’ is fulfilled by Google by putting a banner at the top of the browser (something added during the time when sending an email became an AJAX call, instead of a page submit):

And by maintaining a ‘Sent Mail’ folder which offers of view of all email that have been sent:

Features Within Features

Font Editing

Even the small operations in the email text editor itself are split into functional and confirmation aspects:

The functional aspect is invoked when the buttons are clicked and the functional operation that is performed is to modify the underlying text representation (I believe Html).  What is the confirmational aspect? Why the WYSIWYG visualization!

Spell-Checking

The spell-checker confirms by high lighting the misspelled words. The functional aspect is the looking up of each word in a dictionary:

In the Chrome browser, misspelled words are just high lighted without invocation (no button pressing required). This minimizing of the functional aspect is something that is encouraged in confirmation-first development. Good design means minimizing steps as user’s first click is on how to correct the mistake, not click to see if there are any mistakes, then having to click on the mistake.

Iterations introduced a way to tame chaos by successively asking ‘is this right?’. User Stories and XP’s on-site customer foster collaboration, but that conversation is typically about ‘what the system should do’ with the Product Owner left, in scrum terms, responsible for ROI.

ATDD formalized this concept into a set of system inputs and outputs that are meant to represent that ‘if the system can do this’ then it is assumed that we (the development team) have ‘delivered the right thing’.

There are major weaknesses to this model:

1. The inability of customers and users to design software.

Jenea Hayes at cooper design said this very well when she wrote:

Many of our clients come to us with a history of producing bad user interfaces, and they can’t understand why when they have included every popular feature request from their users.

The reason for this is very simple: users are not designers or visionaries. We should no sooner ask them to design a product than we would ask them to write the code.

2. It puts the primary focus on the technology

The conversation is about what the system should do, not on the customer and the ‘why?’ driving the need for software in the first place.

3. It introduces a two-tiered goal system

Development teams can end up in the vulnerable and awkward position of succeeding at what they do, but still having the software fail overall.  One has to wonder what the effect on moral is in such an environment, whether through lack of belief in a real, meaningful goal or through an antagonistic relationship with product management.

4. It encourages mediocrity

Both parties (customer and business) usually have already invested heavily in the process and ‘good enough’ salvages existing effort. It lowers the bar to what is functional, not what is good.

These observations are not entirely new. Techniques like BDD, Specification by Example, and more recently Lean Startup have emerged that are all addressing this same fundamental problem that understanding the customer goals and outcomes is essential in designing the right system. These are good techniques, more people should use them.

Yet they are all techniques for deriving a set of requirements. Desires and outcomes are still *translated* into a feature that is believed to satisfy those goals, largely for the benefit of fitting into a development machinery tuned for delivering features in a pipeline manner. The focus is on defining an input to some function then testing an output.

Why is it that we feel compelled to translate customer desires? Is it perhaps because we believe we must homogenize the development process into one single fundamental unit of ‘feature’ driven by functional requirement?

What if we instead addressed the satisfaction of customer desires head-on and as our top priority?

What does this mean exactly? I propose that we ask the customer this question directly by asking a question framed as an inquiry to what they want to be shown that proves they got the value at a moment in time after the system has been used in the traditional sense of a piece of functionality.

In fact, isn’t this exactly what we do one level down in TDD? We start by asking ‘how can I show that the code worked’ and that test becomes the thing that proves that it does work.

This suggests a natural dichotomy of features into 1) those that confirm that the value was realized (confirmation, or test features), and 2) features that are used as mechanisms to fulfill the requirements of creating the value (functional features). Indeed when we look at software through this lens we can begin to see both types of features. One of the most common examples is presenting a confirmation feature after a data entry feature.

And just like doing test-after instead of TDD, we may, more often than not, find the confirmation to be missing and wish there was better insight into the use of the system. And how often is that confirmation feature dropped or never executed because it is viewed as a ‘nice-to-have’?

Focusing customer conversations in this manner is very revealing. I posted an example from the first time I used this technique. It appears to be the most direct route to talking about what is important to customers and is incredibly sensitive to context. It also lends itself to revealing complexities of stakeholders, dovetailing nicely into the ‘Effect Mapping’ technique recently introduced by Gojko Adzic.

All of this leads us to one more fundamental question: if we have not been doing our ‘test’ confirmation features upfront, what does that say about the amount of churn and the quality of the features we normally do first: those mechanistic, complicated, expensive functional features?

Think about it, the sum total of confirmation features across all stakeholders represents the required output of the functional feature. If we define this upfront we avoid adding unnecessary things to our functional features. In fact we now have the outcome side of a traditional acceptance test.

One has to wonder if the introduction of iterations (not increments) was something of unnecessary thing. I like iterations as a safety net or as a method of successive approxiamation when dealing with an unknown problem or qualitative issue. But it really should be a technique of last resort for validation.

That’s the theory. In the next post, I’ll show an example of how this works in practice.