Right-sizing User Stories

I was asked by a customer to give a talk about right-sizing user stories. Below is the summary I gave them. This is by no means an original bit of thinking but ideas pulled from a number of sources (1, 2), however it made a nice little summary so I thought I’d post it.


A User Story typically takes the form of:

As <type of user>
I want <some goal>
So that <some reason>

So what is the right size ?

There is no right answer !

It pretty much depends on the team. In particular their skill levels, the process they follow and their domain knowledge. All these factors impact the size of a User Story that is right for the team.

A well oiled team, working in a domain they know inside and out can consume and deliver much larger User Stories with ease. A newbie team with little domain knowledge is going to require much finer sized (and easier to consume) User Stories.

Rules of thumb

However, there some rules of thumb that can help you find the right size of User Story for your team:

  • small enough to be understood by the team and be implemented by the team in a short space of time
  • big enough to represent business value in its own right
  • big enough to deliver on its own

A User Story is NOT…

  • A task (e.g. a small bit of work that has no standalone business value)
  • A requirement

Instead a User Story:

  • Groups a set of tasks to be done (which can be used for bottom up estimation if need be)
  • Groups a set of requirements (ideally defined as acceptance criteria)

A User Story is “Done” when:

  • All the tasks have been completed
  • All the acceptance criteria have been met

Some examples

“As a user, I want a new system because the old one no longer meets my needs” is too big (probably even too big as an Epic)

“As a user, I want to register, login and manage my details online” is still too big. It should be at least three User Stories, covering logging in, registering and managing details.

For most teams even three would be too course. Logging in could itself be broken down into three finer grained User Stories:

  • “As a user, I want to log in, so that I can access my private information”
  • “As a user, I want to reset my forgotten password, so that I can login”
  • “As a user, I want the system to remember me, so that I don’t have to log in every time”

These are probably the size of User Story I’d suggest that most teams use. Each delivers a standalone bit of business value, can be easily understood & implemented and can be easily prioritized in a back log.

If you start to create features like “As a user, I want to enter my user ID” and “As a user, I want to push the login button”, then stop, you have gone too far !

Hacking Interview on Radio Hauraki

Last Friday I got to do live radio for the first time! Since I didn’t come across as a complete idiot I thought I’d share the clip with everyone. The subject was hacking and the clip was recorded during the breakfast show on Radio Hauraki.

Unfortunately I miss-heard the question about the Whaleoil hack and landing up talking about the likely attack vector for The Fappening (the August 2014 celebrity photo leaks)… the perils of live radio I guess :)

BTW the tool I was referring to was called ibrute and it took advantage of an issue with Apple’s find my phone service which, did not lock out accounts if successive incorrect passwords were entered. The application simply tries a bunch of common passwords for a list of email addresses you give it and reports back on the ones that worked.

The passwords that the tool uses where the 500 most common ones used by users of the RockYou website that was hacked (the details of around 32 million accounts were stolen). If your password is on this list you should really go and change it right now! And of course never, ever use the same password on different sites. Here is a handy way to come up with unique but easy to remember passwords.

Building a modern web app, some learnings

I recently built a fairly rich web application from the ground up. Whilst I’ve being building web apps since the mid-nineties this little project had a different flavour to it and I thought I’d go over my learnings here.

Firstly why was this project different:

  • its a Facebook app and uses their JavaScript SDK. This means that 99% of the app runs client side with only a small bit of server side code.
  • I’m was the sole developer. Normally I work with 2 or more other developers, focus on the back-end work and leave the bulk of front-end stuff to others
  • rapid development approach. The app was built quickly with me working closely with a UX guy and a designer. Whilst the functionality was locked down early on, the user interface and interactions evolved rapidly and iteratively.

First observation: its so easy

OK that is slightly facetious, but modern CSS and JavaScript frameworks mean that you don’t have to be guru to build nice looking, smooth functioning, cross browser applications.

For this application I used the Twitter Bootstrap CSS framework and the jQuery Javascript framework.

Get a designer

Yes I know I just said that it’s easy and you don’t need to be a guru to create nice looking apps BUT whilst Twitter Bootstrap encapsulates a great design, you are still going to want to customise it.

Designers have the knack of adding the odd image, drop shadow or bit of whitespace that can make a perfectly ok looking web page just suddenly pop. Not to mention the selection of color a palettes and general pixel pushing.

On a similar front having a UX guy on hand is invaluable. If you don’t have one, then read Steve Krug’s Don’t Make Me Think book and then go and find yourself a UX guy  :) 


The Facebook API is now pretty mature and is very stable (compared to the last time I used it a few years ago).

One annoying things is that the calls that you make to explore the user’s social graph (via the FB.api function) are very low-level and the data is returned in a callback. This can make your code very messy, since you often have to chain your app’s logic in the callback function, if your app needs data before it can proceed. For example:

FB.api('/me', function(response) {
  // do something with response here
  // make next api call (with nested callback) here

Additionally if you need to, for instance, retrieve friend profile data you can land up making hundreds of calls:

// grab all my friends
FB.api('/me/friends', function(response) {

    $.each(response.data, function(index, value) {
       // get profile for each friend (this triggers another HTTPS call)
       FB.api('/' + value.id , function(profile) {
         // do something with profile data


Luckily there is a better way, the FB.query and FB.waitFor functions. These let you run queries against a user’s data using a SQL like language (FQL) and then block waiting for the response. This greatly reduces the time it takes to retrieve data and keeps your apps logic a bit simpler:

var query = FB.Data.query('SELECT uid,name,current_location FROM user WHERE uid IN (SELECT uid1 FROM friend WHERE uid2=me())');
query.wait(function(rows) {
    $.each(rows, function(index, value) {
       // do something with friend data here
// rest of app logic continues here


Get it (hopefully this isn’t news to you). This tool is invaluable for web development. It allows you to debug JavaScript, view the DOM, check network traffic and tweak CSS in browser.

It’s also a good idea to test you app in different browsers as you go. During this app’s build I had FireFox, Chrome and IE 8 all running so I could see that everything was working. Luckily by using Twitter Bootstrap and jQuery I had no cross-browser issues at all other then the fact that IE didn’t get nice round corners.

Make sure it validates

The W3C provides a tool for validating web pages. It’s always good to be sure that your pages validate, not just because it is good practice but because it stops browsers from entering their “quirks mode” which often causes odd and quirky behavior.

The Web Developer plugin for Firefox provides a handle shortcut for submitting your local HTML to the W3C validator.

In my case everything validated except for the Facebook namespace declaration and the custom Facebook tags such as fb:like. Whilst there are ways around this I decided on not been too purist.


Try use HTML5 for your app. It works very nicely. For IE browsers (before 9.0) use the HTML5 shim to get some HTML5 support.

However Twitter Bootstrap does not support IE6, so I used this trick to make any IE6 browsers redirect the user to a “browser unsupported” page with tips on how to upgrade their browser. In the __section add the following comment:

 <!--[if lt IE 7]><script type="text/javascript">window.location = 'notsupported.html';</script><![endif]-->

This uses the conditional comments feature of Internet Explorer to redirect IE6 browsers to the notsupported.html page, other browsers will simply treat it as a HTML comment.

Improving load times

It is best practice to load all the CSS files in the section of the page and all the JavaScript files at the end of the page (just before the </body> tag). This makes the page feel much more responsive as the browser can start to render and layout the page before everything is loaded.

Having said that, a complex web app tends to pull in a lot of CSS and JavaScript files and minimizing the number of objects that are fetched from the server is a key factor in having a speedy app.

Ideally you only want your app to load a single CSS file and a single Javascript file. To achieve this in my app I concatenate the CSS files and JavaScript files (in the correct order) and then compress them using Yahoo’s YUI compressor.

Since I wanted this to be a repeatable process I used Ant to create a build script to do this. Firstly the concatenation:

<concat destfile="${tmp.dir}/all.js">
  <fileset file="${www.dir}/jquery.min.js" />
  <fileset file="${www.dir}/jquery-ui-1.8.16.custom.min.js" />
  <fileset file="${www.dir}/jquery.masonry.min.js" />
  <fileset file="${www.dir}/bootstrap-modal.js" />
  <fileset file="${www.dir}/bootstrap-twipsy.js" />
  <fileset file="${www.dir}/bootstrap-alerts.js" />
  <fileset file="${www.dir}/app.js" />

And then the compression:

<exec executable="java">
  <arg value="-jar"/>
  <arg value="yuicompressor-2.4.7.jar"/>
  <arg value="${tmp.dir}/all.js"/>
  <arg value="-o"/>
  <arg value="${tmp.dir}/all.js"/>

Now during development you don’t want to be dealing with concatenated and compressed files so my PHP pages contain a snippet like this:

if ($config['mode'] != 'prod')
    <script src="jquery.min.js"></script>
    <script src="jquery-ui-1.8.16.custom.min.js"></script>
    <script src="jquery.masonry.min.js"></script>
    <script src="bootstrap-modal.js"></script>
    <script src="bootstrap-twipsy.js"></script>
    <script src="bootstrap-alerts.js"></script>
    <script src="app.js"></script>
    <script src="all.js?@buildtimestamp@"</script>

With mode getting set in my app’s config file.

Of course there are a ton of other things you can do to tune your app. Get the YSlow addon for Firebug and run the report on your pages to see what can be done.

Cache busting

Ant can also very helpfully update parts of your files whilst copying them around. This can be used to burn in all sorts of things, like version numbers and build timestamps. It can also be used create a effective cache buster when a new version of your app is released….

Firstly you need to set up an Ant property with an appropriate value:

  <format property="buildtimestamp" pattern="yyyyMMddHHmmssSSS" locale="en,UK"/>

Then in your HTML you can append @buildtimestamp@ following to file references:

<link rel="stylesheet" href="all.css?@buildtimestamp@"/>
<script src="all.js?@buildtimestamp@"></script>

Then lastly apply a filter in Ant when you are copying the files around:

<copy todir="${tmp.dir}">
  <fileset dir="${www.dir}">
    <include name="**/*.php" />
    <filter token="mode" value="prod" />
    <filter token="release" value="${rel}" />
    <filter token="buildtimestamp" value="${buildtimestamp}" />
    <filter token="builddate" value="${builddate}" />

PHP config file

To keep things nice and clean, I created a config.php file looking like this:

<?php if ( ! defined('CONFPATH')) exit('No direct script access allowed');

// set this to '@' + 'mode' + '@' during development so that style sheets and javascript files are individually included (see index.php)
// ant build scripts will replace this at build time
$config['mode'] = '@mode@'


Then in my other PHP files I pulled in the config file using:

   require_once CONFPATH;

As you can see from the comments and the Ant snippets above, I overwrite the mode value with _‘prod’_ during my Ant build process to ensure that my compressed .js and .css files are used.

Miscellaneous files

Finally make sure you add a favicon and a robots.txt to avoid annoying 404 webserver logs. For fun why not add a humans.txt too.


Well that pretty much covers it. Hopefully there are one or two new  ideas here that you can use in your apps. Feel free to post any questions in the comments section below.

Ask Gremlin…

I’ve received a couple of interesting emails recently from people asking for advice. I figured my answers might be of use to others so here are the (redacted) emails:

Android App

The email:

I am wanting a Android Application designed for me. I am wanting to know a little more about Android Applications and how to go about getting one designed for me. How do the laws work around making a app and around how much would someone have to pay to get one designed? If a Android developer was to make a app for me would the rights of that app be mine or the creator? Sorry for the inconvenience I’m really new to this. Any information would be appreciated.

My response:

Hi ****,

A few years ago there was a move in NZ to better clarify ownership of intellectual property and copyright for “commissioned works” which includes software developement. However this amendment did not pass see: http://www.med.govt.nz/templates/ContentTopicSummary____18836.aspx

Although there are some existing laws that cover this area, what you want to ensure is that there is a clause in any contracts you sign (and you should ensure you have a contract with anyone who is written apps for you) that you own ALL the IP and copyrights on the work that is produced.

In terms of how much will it cost, the answer is it depends on how complicated the app is :)

Basically there are two general models followed for software development: “Time and Materials” (T&M)  or Fixed Price.

With T&M you generally pay the developer an hourly rate. For software development you can pay anything from $25/hr through to $150/hr. Typically the more senior or skilled the person, the higher their rates. Of course paying more doesn’t guarantee quality or success.

With Fixed price the price is determined ahead of time and that is the amount you will pay for the completed software. Whilst this seems a “safe” option, software development is often complicated and unexpected things turn up all the time, as such Fixed Priced contracts are often padded with a “contingency” to ensure that the developer makes money. If the project looks risky the contingency can be as high as 50% which means you would be paying far more for the work then it is worth. The other issue with fixed price contracts is that they often have a “change request” (CR) process which allows the developer to make additional charges for work (eg features of the app) that were not covered by the original specification (or “scope”) of the project. CR processes are often confusing & abused and you land up paying way more then you intended to in the end.

The best way to “protect” yourself against unforeseen costs is to be very, very, very clear on what you want to have built. In software development this is often called “scope” or the specifications of the project.

For an Android app I would suggest that you create what is called a wireframe or mockup of the app. You can use a tool such as http://balsamiq.com/ or http://yeblon.com/androidmockup/ or even paper & pen and sketch out each of the screens of the app, add notes about what each screen should do and how you navigate from one screen to another.

Once you have your wireframe sorted you can then shop around and get different quotes from different developers to find a price and developer you like. If you think your idea is particularly unique, you might want people to sign a non-disclosure  aggreement (NDA) before you show them your wireframes or talk to them about the app.

Lastly you might want to try and write the software yourself ! Have a look at http://appinventor.googlelabs.com/about/ as a “gently” intro to Android development. It will let you create a working prototype that you can actually run on your phone :)

Hopefully the above has been helpful.


QR code generation

The email:

I saw your comment on the hack-a-day QRcode post.  You seem to have quite a bit of experience in QRcodes and other scanning apps.  One thing that I have been looking for (and maybe you might be able to help) is a program that creates unique QRcodes from list of URLs.  I’m helping out a non-profit **\* with their website and I was trying to find an easy solution to automatically create printable QRcodes for all of the ***\** at once.  This way each **** has their own QR code to an info page on a WordPress blog.  It could be done manually, but the ** change every two weeks! :)

A bonus would be automatically taking Bitly URLs and turning them into a bunch of printable QRcodes.

Just thinking

My response

Hi *****,

The Google Charts API can be used to quickly create QR codes. Check out: http://code.google.com/apis/chart/infographics/docs/overview.html and http://code.google.com/apis/chart/infographics/docs/qr_codes.html

So the following #aliases: https://chart.googleapis.com/chart?chs=150×150&cht=qr&chl=http://blog.rabidgremlin.com  would create a 150px by 150px .png QR code containing a URL to my blog (http://blog.rabidgremlin.com)

You could probably use a tool such as Curl or WGET to script the fetching of the bar codes.


What I did last week – 15 Feb 2011

Actually it’s more what I did last month.

RC simulator

A mate of mine bought himself a swish RC quad-copter. As part of the package he bought Phoenix RC. It is a simulator that allows you to plug your RC controller into a PC and you can then practice flying (and crashing) virtual RC models before tackling the real ones. Very useful and it clearly proved that I should never attempt to fly a real RC helicopter.


Believe it or not, I’m actually getting paid to hack a Kinect. Im using the OpenNI framework so hacking really consists of installing the software and then using a nice high-level framework that does all the hard work for you. I’ve been very impressed with the skeleton tracking.  I’ve been able to simultaneously track 3 people with full skeletons without any issues.  This is the guide I used to install the base software. You should also check out the Ogre and Unity demos.


Whilst tinkering with the Kinect I ran through the Unity 3D platformer tutorial. Unity is very impressive. If you want to create a 3d game I’d start here.  The basic version is free. The cross platform nature of the engine is impressive to.

Auckland Buses app

I finally got around to releasing my Auckland Buses app for Android. It only took a few hours to put together.  I’m experimenting with an ad supported model. The app has about 225 users, averages around 25 impressions a day. So far I’ve made 49c so not really a money maker :) What is interesting is the fairly poor fill rates I get some days.  If you had marketing dollars to spend,  mobile ads might be the way to go as not many people seem to be tapping them.

That’s about it…

MeterRec released

Icon for MeterRecI’ve just released my first purchasable app on the Android market.

The app is called MeterRec and it allows you to easily record readings for gas, water and power or other similar meters.

These readings can then be exported as a .csv file for manipulation and graphing in applications such as Excel.

This app is ideal for property managers, flat mates or those (like me) who just want to keep tabs on what they are using.

If you have an Android phone then point your barcode scanner at the QR code above, to get a link to the app in the market. For those of you without an Android device, here are a couple of screenshots:

Playlist dumper for iTunes

I’ve been meaning to write this bit of software for a while now, its a simple app that dumps out all your playlists in iTunes into .m3u playlist files.

I use it to generate playlists that my HTPC (running Boxee) can play.

It’s a .NET app. You can download it here: PlaylistDumper_v101.zip

If the “dump folder” is the root of your music library then the .m3u file will contain relative paths which is useful for playing across network shares.