Writing good User Stories

~2m 0s
February 20, 2014

First, it should be noted that not all stories are "User Stories". For example a developer might be tasked with manually running some script. The Story might simply be "run the fooberry script".

For everything that effects the UI, use a template:

As a < type of user >
I want < to perform some task >
So that < I can achieve some goal >

Note that it's all about what the user wants. This isn't about instructing what change to make to a system. It's about advising implementers on what the desires of the user are.

Sizing, details, content

Now, everyone says user stories should be "testable", and "small", but what does that mean?

Stories should be "Testable"

You've heard it before, but its a horrible way of expressing the intent. In general, a story is not directly testable. A Story is only testable through its Acceptance Criteria.

Acceptance Criteria?

Each Story should have a compliment of Acceptance Criteria which cover every interaction, and outcome of the Story. Think of it this way. If you write code that meets every Acceptance Criteria and nothing else your coding work should be done. You should not need to write anything else in order to satisfy the Product Owner. Furthermore, you should be able to write a unit or functional test for each acceptance criteria. If you find your test is testing multiple aspects of the system then your acceptance criteria is too large in scope.

For example: if you've added a new page to your app one of the acceptance criteria might be "Administrative users will see a link to the new page in the upper nav. on all pages" This acceptance criteria would pass regardless of where the new link appeared in the "upper nav." If the Product Owner cares where it appears then the criteria isn't specific enough. Note that it also specifies what pages it will appear on. Without that you could put it on the "wrong" page and still pass the criteria.

In XP (Extreme Programming) they use a 3"x5" index card to create all their user stories. The story (in template form) goes on the front, and the acceptance criteria go on the back. The rule-of-thumb is that if the acceptance criteria don't fit on the back of the card, then the story is almost guaranteed to be too big.

Story Sizing

How small is too small? A Story is too small if, by itself, it provides no business value, like this: "As an Administrative User I want to have a link to the new page so that I can navigate to it." Unless someone's already created and deployed the new page, it's a link to nowhere. The next question, of course is how big is too big? I'd say it's too big if it can still be decomposed into multiple smaller pieces of deliverable business value.

User Story Decomposition

General Tips

  • Know your users, before you can write a story about what a user wants, you need to know who your users are. Put together, and commonly agreed upon set of user Personas, and use those persona names when writing the "As a... " portion of your user story. E.g. "As an Accounts Manager I want..."
  • Focus on the user, not the product. Keep your stories focused on the user's goals, and helping them to achieve them.
  • Start big, and decompose It's generally much easier to write an "Epoch" level story (one that comprises many units of business value) and break that down into increasingly smaller stories, than it is to start with fine grained stories.
  • Use index cards (to start with at least). The physical limitations of the card really help make it obvious when a story is too large, because you can't fit it, or it's acceptance tests on one side of a card (unless you write in verrry small print, and that's cheating).
  • Acceptance tests should be automatable If you can't automate the acceptance test, it's probably not a good one. They should be very focused, and very precise.
Like this post? Click the heart above to give it a kudo. :)

Finding the Github Pull Request for a topic branch

~2m 0s
December 24, 2013

Finding the Github pull request associated with a branch.

Work on a large enough project, with other people and sooner or later you're going to find some commit, or branch, and want to know what was in the pull request that merged it in. Maybe you want to see what other commits got merged over at the same time. Maybe you want to see what the diff was at that point in time. But, how do you get from a branch name to a pull-request.

The key to solving this is knowing that pull requests are actually branches. They're just... hidden branches. So, first you start tracking them...

Locate the section for your github remote in the .git/config file. It looks like this:

[remote "origin"]
    fetch = +refs/heads/*:refs/remotes/origin/*
    url = git@github.com:joyent/node.git

Now add the line fetch = +refs/pull/*/head:refs/remotes/origin/pr/* to this section. Obviously, change the github url to match your project's URL. It ends up looking like this:

[remote "origin"]
    fetch = +refs/heads/*:refs/remotes/origin/*
    url = git@github.com:joyent/node.git
    fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

Now, after a git fetch origin you can say git checkout pr/999 to checkout pull request number 999 as a local branch and diff it, or do pretty-much anything else with it.

Once you've got that set up, it's just a matter of comparing your local topic branch to the other branches in your system to find other branches that point to whatever branch you're interested in.

I use a shell script called git-find-twins which iterates over the known branches (including pull request branches) and finds any whose tree-ish matches that of the current branch. You can find the latest source here in Github.

[Note: My apologies for the disappearing code on the right side in these examples. Just grab the source from the link above.]

# Finds other git branches whose HEADs point to the same 
# treeish as this branch.

# thanks to mockinterface on 
# http://stackoverflow.com/a/20756047/13973
# for showing how to do this.

echo "Looking for branches pointing to: $(git rev-parse HEAD)"
git for-each-ref --format="%(refname)" | \
    xargs -I refname   \
    sh -c '[[ $(git rev-parse HEAD^{tree}) == $(git rev-parse refname^{tree}) ]] && echo refname'
echo "DONE"

Add that to your path, and make it executable then check out the branch you want to find the pull request for, and run your new shell script with git find-twins (note the space) and you'll see output like this.

$ git find-twins
Looking for branches pointing to: cb3c2dcf606a0a26107131697dd37aef53d44aad

That last one is what you want. 530 the number of the pull request, which you can put into an URL to see the pull request. Now, you're probably saying "Yeah, but what URL?" well, one way to get the correct url is to just bring up any other pull request in the current project and change the number in the url. Or you can add this shell script, which I call urlforpr which generates an url for the pull request number in the current repo. It's based on the assumption that "origin" is the Github repo. If it isn't you'll need to tweak what remote it gets its info from. You can find the latest source here on Github

[Note: My apologies for the disappearing code on the right side in this example. Just grab the source from the link above.]

# when run from a git repository, and passed the number 
# for a pull request, it will generate an url for 
# where to find it on Github. This assumes that
# "origin" is pointing to the Github repo.
# This will work with Github Enterprise too.

if [ $# -eq 1 ]; then
    ROOT_URL=$(git config --get remote.origin.url | \
        sed s/.*@// |sed s/\.git// | sed s/\:/\\//)
    echo "https://$ROOT_URL/pull/$1"
    echo "Please pass in a Pull Request number"
    echo "Note that this should be run within a git repository"
Like this post? Click the heart above to give it a kudo. :)

Bonsai Coding

~3m 0s
December 06, 2013

Writing code is a lot like maintaining a Bonsai Tree. If you stop pruning it it'll stop being a Bonsai and turn into a bush. Little tweaks, frequently aesthetic ones, will help to keep it beautiful and under control. It will still grow in unexpected directions, as other developers make changes, but careful pruning will keep it balanced, and healthy.

What is "careful pruning" then?

Each file is a branch on our tree. The methods, are leaves. We come in to work and start examining one of the branches. Some days we need to encourage it to grow a specific way by adding a feature. Some days we make little snips to correct a bug. But what happens if, upon examining your branch for other reasons, you discover that it's grown into spirals and knots. You can't reach your clippers in to snip the leaves you need. You can't do much of anything without difficulty and frustration, and frankly, it looks like crap. The unexpected spirals and knots need to go.

This, however, is the point where you'll hear other developers saying "No! Don't do that!" They're upset, because your task wasn't related to the knots and spirals. You were just there to trim some leaves. If you go and get rid of the "other" problems then how will they be able to tell where you trimmed?

To abandon the metaphor for a minute, they're concerned that the diffs will be so filled with aesthetic changes that they can't see the changes that were relevant to the bug fix, or feature add. And, they have a point. Being able to look back and understand the changes another developer made is a very valuable tool. But some developers get so obsessed with this idea, or so beaten down by others who are obsessed with it that they say things like this,

"The rule for controlled development is that if the line is not relevant to the fix, you do not modify it. If we want to go through and fix all the lines in our product that are over 80 characters, then we log a bug for it." - A rule you shouldn't follow

This solution will never leave us with a beautiful tree. I don't know of any professional developer who has the time to deal with tickets that are that low priority, and no-one wants to anyway.

If you accept that there is value in making the line / file readable, then you must also accept that there will be change unrelated to any bug fix or feature request. You must also accept, that if those changes get put off for "later" our tree will become a bush, and require so much work that it will be almost unrecognizable the day after the change.

So, how do we balance these two concerns? How do we make readability changes to our code without obscuring the functional changes? My recommendations are as follows.

  1. It should be acceptable for whatever method you're directly trying to enhance or fix to be refactored for readability. Even if you're refactoring a 20 line method, for a one line fix. To do otherwise is like having a child make their bed but leave their clothes and toys strewn about the floor. Don't do a half-assed job. Leave the method better than you found it.
  2. Separate other aesthetic changes out into separate commits. It would be nicer if you could commit the fix, then commit the aesthetic changes, but we frequently need to make the aesthetic changes in order to make the code readable enough to understand it. So, make it readable, but leave it broken. Commit that change. Then fix it and commit that change.

The downside to 2 is that you have to instruct reviewers to review specific commits, rather than the changeset as a whole. So, an alternative is to make the aesthetic changes, create a pull request / request review of your branch to be merged, and then, once that's done create another pull request for the bug fix. I think it's a judgement call, and the appropriate choice depends on the situation.

As per usual, if you've decent test coverage everything becomes much easier. Code reviewing the aesthetic commits can be just a matter of seeing if the tests pass, and giving it a quick glance to make sure the other developer didn't go all crazy-pants with their changes, like changing the indentation style to something no-other files use. You don't have to stop and consider the funcional impact of the changes, because there shouldn't be any. "Yup, still compiles, still passes the tests, looks more readable. Approved!"


Codebases are like Bonsai Trees. Regular aesthetic changes are as important a part of keeping your codebase healthy as regular refactorings. Some trivial changes to how you commit your work can elimanate the diffing problems that arise when combining fixes / features with aesthetic changes.

Like this post? Click the heart above to give it a kudo. :)

The Daily Team Tracker Worksheet

~1m 0s
August 22, 2013

The Daily Standup Meeting is a core aspect of Agile development. The simplified idea is that you want to start the day with a very quick status check of what everyone's working on, and helps "...to coordinate efforts to resolve difficult and/or time-consuming issues".

But, how do you keep track of the things your minions are working on today and deal with your own tasks, and 400 daily interruptions? For me the answer was to put together the Daily Team Tracker Worksheet.

Daily Team Tracker

The idea is simple. Each morning, as you go through your Daily Standup write down what each person will be working on today. If they expect to complete the task today there's a little checkbox to indicate that. There is, of course, another to indicate it's done, a notes section, a place for emergent tasks, and more.

When 3pm comes around and I'm wondering, "What was Charles working on? Was he expecting to finish that today? Should I be checking in or leaving him alone?" I can check my sheet and see.

It's also good to have prior days sheets because you can easily see that at task that was supposed to be done "today" has been on someone's plate for three days now, enabling you say "Wait, weren't you expecting to finish that two days ago? What's gone awry? Is there anything I can do to help, or any lesson we can take from that?" (It's all about the Kaizen baby). Some of that will, of course, be covered in your stand-up, but sometimes it's good to have that reminder.

There are two versions of this:

  • Daily Team Tracker PDF (for teams of over 3 people).
    • Page 1 is a the 3 person view with section for notes and diagramming.
    • Page 2 has sections for 5 more folks with a mini notes / diagram section
  • Daily Team Tracker PDF 2 Sided (for teams of 3 or less)
    • Page 1 and 2 are the same 3 person view so that you can print it on both sides of a piece of paper and save some trees.
  • Daily Team Tracker OmniGraffle file If anyone out there has OmniGraffle and feels like tweaking the original.

This file is (cc) 2013 K Rhodes ( masukomi.org ) and distributed under the Creative Commons Attribution-NonCommercial-ShareAlike 2.5 License.

Like this post? Click the heart above to give it a kudo. :)

[Review] CruxSKUNK iPad keyboard / case

~6m 0s
June 01, 2013

The backstory

Once upon a time there was a Kickstarter to make the world's most awesome keyboard / case ... thing to "Turn your iPad® into a laptop". As with most hardware projects on Kickstarter the expected delivery date came and went, and came and went again, but I feel the folks at Crux did a great job of keeping the backers informed, and the reasons it got set back almost always boiled down to them not being willing to accept half-assed Chinese manufacturing even if it would have gotten it into our hands sooner.

They really wanted to make the best product they could. They went so far with this that they actually lost money on each one that was made, and these are guys aren't new to manufacturing hardware. They've had similar products built in China before. When it comes to something like this, I'm ok with having to wait a bit longer to get a better product.

So, did they deliver?

First impressions

CruxSKUNK Triptic

The first thing you notice is the weight. This is not a flimsy POS product. They promised a CNC milled block of aluminum with a quality level that was right on par with the Macbook, and they came pretty close. Is it as beautiful as a Macbook Air? No, but we knew that going in. This is essentially a really fancy picture frame for your iPad with an attached keyboard. They could have put a sheet of aluminum behind the iPad's back, but it would have made the whole thing thicker and heavier. The reason I have to say "pretty close" is that Apple's manufacturing standards are very, very high and the tolerances aren't just good, they're precise. So, for Crux, or anyone else, to get "pretty close", is pretty damn good.

The case it comes with is actual leather, with a layer of padding and a fuzzy fake fur lining to keep your baby safe. Will I use it? Probably not. Is it nice? Yes.


Inserting the iPad was pretty simple. By default the little hinges that hold it in at the bottom are configured for an iPad 2 I suspect. The iPad 3 and 4 are a bit thicker, so I had to grab the included alan wrench and loosen them up (as instructed by the user manual) so that they would fit over my iPad 3. I also managed to put the iPad in backwards which obscured all the ports, but as soon as my foolishness was pointed out I just opened the hinges, flipped it around, and voillá the cutouts for the the ports and button lined up perfectly, but the space around the ports is only barely adequate. The headphone jack works fine with the Apple headphones, but anything with a thicker plastic portion won't fit. The main 30 pin port is only enough for the power adapter. I have to press the iPad "into" the case and / or pull down on the edge of the case to make enough room for my connector cable to fit. The adapters for the Apple Camera Connection Kit don't fit at all. I have to take the iPad out of the Crux Skunk to use them. Not a huge deal, as I don't use them that often, but I suspect I'll be using them much more frequently on the road and it'll be annoying then. The HDMI adapter does fit either, so you cross this right off your list if you're hoping to use it for presentations because even with pressing you can't make it fit while in the case. I can't comment on how accessible the Lightning port on the iPad 4 would be.

My first thought upon seeing my iPad in it's new "laptop" incarnation? "It's so wee!" Visually it's pretty good. The keyboard comes up through an aluminum plate, which is fine, but I'm not thrilled with visuals the seam that follows around its edge meets up with the base. Apple chose put the flat plate on the bottom of the Macbook so that you're not seeing it every time you use your laptop. I think this would have been a better choice for Crux, even if it did necessitate the use of screws, which Crux has managed to avoid. Also, the tolerances along that seam are good, but not Apple good. You can see it in the top right photo. I just can't help but think "Oh look, there's a metal plate that's been snapped to the base", every time I look down at it, and I don't want to think that. I don't want to be aware of that at any level. It should be hidden from me.


Pairing it was pretty straightforward, except that I pushed the "LED window" instead of the "Sync button" because the "LED window has the light that they were talking about seeing. Doing so felt wrong, but it still moved significantly as if it was a badly done button. But no, it's a thing that looks like a button but really isn't, and moves in a disconcerting way when pushed by someone who's not paying close enough attention. Fortunately, I should never have to push the "Sync button" again, and it should be noted that if I'd read the instructions more carefully I wouldn't have pushed it in the first place.


The keyboard itself feels... well it feels pretty good. The keys on a Macbook Pro have a softer feel at the terminus of your stroke. These have a little bit more of a "whack" at that point. Is it bad? No. It's just different. You might start to feel it after an hour or more of typing. As for the layout, my fingers don't feel even remotely cramped like they do on a typical netbook, but the key layout is smaller than that on the Apple Wireless Keyboard.

The CruxSKUNK comes with a variety of useful specialty keys: home, search, slideshow, languages, screen toggle, copy, paste, a lock button, plus music and volume controls. Some work, some don't. I don't know if this is a bug in Crux's bluetooth software or just functionality that's not supported by my older iPad 3. The ones that don't work are: language, copy, and paste. I was really hoping those copy paste buttons worked. Alas, "comnd+c" and "comnd+v" (not a typo) do not copy / paste either. But, You can use shift+arrow keys to select text like with any other keyboard, and that's a hell of a lot better than the touch based text selection tools.

I've typed about about 1,500 words on the thing so far, and I'm enjoying it. I've always been painfully slow typing on iOS devices. Now, I can touch-type full speed (~100 wpm) without issue. Geeks like me will be happy to know there's a way to convince your iPad to use a Dvorak layout with bluetooth keyboards like this one. So all 4 of you can rejoice. Yay.

The lid / hinge

Closing and opening the lid sleeps and wakes the iPads screen respectively, as you'd hope. The hinge is designed such that you can keep opening until the back of the iPad is directly against the bottom of the case. They call this "Movie Mode." I guess the idea is that you could flip it over into an A-frame and set it on something. Nifty. Will I use it? Possibly. Only time, and travel, will tell. I doubt I'd use it in day-to-day life.

Speaking of the hinge. There were a couple revisions in the hinge during production and I think they've absolutely paid off. It feels solid, and reassuring. The iPad's weight is not going to gradually pull it open. On the downside, the hinge is so strong that you can't actually close the "lid" all the way, or more accurately, you can close it all the way but the hinge opens it back up about an eighth of an inch as soon as you let go (see the photo above), which looks a bit crap if you ask me. It makes me wonder if that's one of the reasons they included a case.


I recognize that, having just received it, and only typed a thousand or so words on it, it's still pretty early to make any claims about it's long term value, but I think that this is just the beginning of a radical transformation in how I interact with my iPad. Previously, typing on the thing was so frustrating that I wouldn't even respond to tweets. I'd switch over to the laptop. Now, I'm typing 1,500 word articles on it.

But, it does what it claims and turns your iPad into a laptop, which is absolutely not what some people want. The iPad is a spectacular tablet, so you definitely sacrifice something when making it into a laptop, and while the wee hinges that hold in the iPad are easy to open or close, it's not really the kind of thing that you'll be wanting to pop your iPad in and out of constantly.

Is it better than just using an Apple Wireless Keyboard? That depends on who you ask. I think the Apple Wireless Keyboard is great, but using it with an iPad is crap unless you're sitting at a table or desk. With the CruxSKUNK I can type on my iPad with it in my lap, at a desk, or anywhere else.


For those curious, yes, this post was created entirely on the iPad using Writing Kit, and Diptic, and typed on my CruxSKUNK. If you like Markdown, and you need to lookup information (and URLs) on the web whilst writing things, I highly recommend Writing Kit.

Like this post? Click the heart above to give it a kudo. :)