Shaving a Yak, Beside the Bike Shed

Because this is being posted to the Big Bad Internet™, I feel the need to disclaim up front that these terms are not my own, nor are my definitions necessarily the canonically ‘correct’ ones. If you get to the end of the post though, you’ll see that that doesn’t matter. This post is one of hopefully a few, where I capture some known ideas but with my own style and analysis. This is primarily being driven by a desire to give some common concepts that I discuss a home that I can link to, where existing descriptions around the internet may not capture my exact personal views.

A mark of maturity that I’ve noticed in effective teams is an evolved language: they have their own catch phrases, and shortcuts that make communication so fast and efficient within the team. Intention is clear, ambiguity is reduced, and people spend less time analysing subtext that isn’t there.

This culture of communication is heavily rooted in strong interpersonal relationships, which do take some time. However, I’d like to argue that we can actively develop some of this communication culture.

Last month, I spent a week with a software engineering team in New Zealand. Their organisation is in the early stages of trying some big, bold, new ideas, and this team needs to support these somehow. The roadmap is still a little fuzzy, but everyone appreciates that they have a lot of work ahead of them. Success will be heavily influenced by spending the just the right amount of time on the right things, but this is a perilously thin path to success with cliffs and chasms everywhere they look.

To stay in check, everyone on the team needs to feel comfortable to question the validity or extent of a task. Equally, they need to still feel comfortable when on the receiving end of such a question. In many teams, this question might come across with phrases like “Isn’t that enough already?”, or “Is this gold plating?” These often come across as confrontational though, seeming to cut away at the value of the work that somebody has been doing. There are nuances open to interpretation, because as obvious as they may seem, the intent of the phrases is not necessarily clear.

I introduced the team to two new phrases:

Yak Shaving

Your home office chair is making an annoying creaking sound because of a loose bolt. You could tighten it easily, except it uses a hex head and you lent your bit set to your neighbour. You can’t ask for them back, because you first need to return something to him: a special anti-allergy pillow that you borrowed for a friend who was staying last week. But you can’t just return the pillow either, because the dog got into it and ripped half the stuffing out. You don’t want to tell him, because it’s filled with a special yak fur that’s hard to come by, which he needs for his son when he visits: you want to fix it yourself first.

The next thing you know, you’re down at the local zoo, shaving a yak, all to stop a squeaky chair.

All of the decisions to get there were individually justified, but at some point you drift too far away from the original goal for them to still make sense as a whole chain. Just buy a new bit set, or give him some money for a new pillow. Or both. But don’t go and shave a yak.

As Seth extrapolates in his description:

This yak shaving phenomenon tends to hit some people more than others, but what makes it particularly perverse is when groups of people get involved. It’s bad enough when one person gets all up in arms yak shaving, but when you try to get a group of people together, you’re just as likely to end up giving the yak a manicure.

Bike Shedding

This one is from Parkinson’s Law of Triviality, and Wikipedia’s summary is best:

Parkinson observed that a committee whose job is to approve plans for a nuclear power plant may spend the majority of its time on relatively unimportant but easy-to-grasp issues, such as what materials to use for the staff bikeshed, while neglecting the design of the power plant itself, which is far more important but also far more difficult to criticize constructively.

Back with the Team

These two phrases each provided distinctly nuanced versions of the original question.

In the way I try to introduce these phrases, “Are we yak shaving here?” says “I can see all the decisions you’re following, and they all seem legitimate. Standing back here though, with a fresher set of eyes, do you think we are drifting a bit too far from the original goal?” Slightly differently, “Are we bike shedding?” is an explicit call of triviality, but recognizing that it’s an easy trap.

Your team’s definitions can vary; what’s more important is that we had a conversation about how we’d communicate. We took a funny story about yaks, and used that to define some phrases that were relevant to the team. Now, when the team hit these scenarios, they can use one of these phrases knowing that the nuances have been pre-discussed and agreed on.

In truth, in this scenario I actually only told these stories to two members of the team. Within a few hours though I heard them describing their own variants of the story to others. That’s another thing that’s great about these types of communication devices: humans communicate better with stories than dry, independent facts. (You might notice, that for this entire blog post, I just told you a story. J)

Related reading (manually curated by me):

Podcast: Graph databases and Neo4j, with Richard and Carl from .NET Rocks!

Listen to .NET Rocks! #949

This is what happens when you phone me up at 6am on a Saturday morning: you get a surprisingly energetic Tatham babbling about discussing Neo4j and graph databases for an hour. There are even some nice bird sounds in the background towards the end, as they finally woke up too.

We discussed what graph databases are (as opposed to charts!), some domains where you might use one, how they relate to other stores like document and relational databases, query performance, bad database jokes, my obsession with health data (,, the Cypher query language, ASCII art as a job, Readify/Neo4jClient for the .NET folks, and some Neo4j+NewRelic.

Useful? Help the Children.

If this podcast was useful to you, perhaps you could donate to my next charity cycle? I’ll be cycling the first leg of the 26 day, 3,716km Variety cycle. Variety, the Children’s Charity is a a national not-for-profit organisation dedicated to transforming the lives of children in need. Variety’s vision is for all children to attain their full potential; regardless of ability or background – and their mission is to enrich, improve, and transform the lives of seriously ill, disadvantaged and special needs children., and good ways to learn new tech stacks

Besides just being a cool domain name, it’s actually quite a useful tool. Wondering how your code responds to an HTTP 418 response? Point it at and find out.

Aaron and I originally built this as a way of learning Ruby, Sinatra, HAML, Sass, Git, Heroku and other funky tool chains. Several years on, left unmaintained, something about our app finally made it incompatible with Heroku’s hosting layer and it all shutdown. Our singular name really rang true here: every request returned a 503. Oops. We already had an ASP.NET-based re-write waiting in the wings, so we pushed that up to Windows Azure Websites and everything came humming back to life.

Want to learn a new tech stack or tool chain? Skip the contrived examples and actually build something simple. It’s amazing how often these turn into cool little tools that stick around for time to come.

Web Forms MVP: Now with less cobwebs

TL,DR: is now just a redirect to

Back in early 2009, Damian and I released our first builds of Web Forms MVP.

GitHub and BitBucket were each less than 6 months old. CodePlex was the place to be for .NET devs, and I think our code was originally in either Subversion or TFS. We needed a wiki, but CodePlex was pretty clunky for that, so we set up a MediaWiki instance on a tiny VM somewhere, running inside Microsoft Virtual Server 2005. Funnily enough, this was all getting pretty unstable. Our wiki has been down almost 50% of the time in recent weeks.

Personally, I was actually a little bit surprised about how many people cared that the wiki was unavailable. This was a promising sign, so we needed to fix the problem.

Today, we migrated to GitHub.

  1. Code was converted from Hg to Git, then pushed to GitHub
  2. Wiki content was converted from MediaWiki to Markdown, then pushed to GitHub wiki
  3. Release notes were migrated to GitHub releases, against the same tags
  4. was redirected to
  5. CodePlex was gutted of content wherever possible, and changed to link to GitHub

The project is still classed as “done” for Damian and I (see my Dead vs. Done post). While we’re not actively investing time in any further versions, publishing it to GitHub gives more reliable access to the content, and makes it easier for the community to fork the project as they see fit.

An Approach for More Structured Enums

The Need

I encountered a scenario today where a team need to increase the structure of their logging data. Currently, logging is unstructured text – log.Error("something broke") – whereas the operations team would like clearer information about error codes, descriptions and accompanying guidance.

The first proposed solution was a fairly typical one: we would define error codes, use them in the code, then document them in a spreadsheet somewhere. This is a very common solution, and demonstrated to work, but I wanted to table an alternative.

This blog post is written in the context of logging, but you can potentially extend this idea to anywhere that you’re using an enum right now.

My Goals

I wanted to:

  • support the operations team with clear guidance
  • keep the guidance in the codebase, so that it ages at the same rate as the code
  • keep it easy for developers to write log entries
  • make it easy for developers to invent new codes, so that we don’t just re-use previous ones

A Proposed Solution

Instead of an enum, let’s define our logging events like this:

public static class LogEvents
    public const long ExpiredAuthenticationContext = 1234;
    public const long CorruptAuthenticationContext = 5678;

So far, we haven’t added any value with this approach, but now let’s change the type and add some more information:

public static class LogEvents
    public static readonly LogEvent ExpiredAuthenticationContext = new LogEvent
        EventId = 1234,
        ShortDescription = "The authentication context is beyond its expiry date and can't be used.",
        OperationalGuidance = "Check the time coordination between the front-end web servers and the authentication tier."
    public static readonly LogEvent CorruptAuthenticationContext = new LogEvent
        EventId = 5678,
        ShortDescription = "The authentication token failed checksum prior to decryption.",
        OperationalGuidance = "Use the authentication test helper script to validate the raw tokens being returned by the authentication tier."

From a consumer perspective, we can still refer to these individual items akin to how we would enums – logger.Error(LogEvent.CorruptAuthenticationContext), however we can now get more detail with simple calls like LogEvent.CorruptAuthenticationContext.EventId and LogEvent.CorruptAuthenticationContext.OperationalGuidance.

More Opportunities

Adding some simple reflection code, we can expose a LogEvents.AllEvents property:

public static IEnumerable<LogEvent> AllEvents
        return typeof(LogEvents)
            .GetFields(BindingFlags.Static | BindingFlags.Public | BindingFlags.DeclaredOnly)
            .Where(f => f.FieldType == typeof(LogEvent))
            .Select(f => (LogEvent)f.GetValue(null));

This then allows us to enforce conventions as unit tests, like saying that all of our log events should have at least a sentence of so of operational guidance:

[TestCaseSource(typeof(LogEvents), "AllEvents")]
public void AllEventsShouldHaveAtLeast50CharactersOfOperationalGuidance(LogEvents.LogEvent logEvent)
    Assert.IsTrue(logEvent.OperationalGuidance.Length >= 50);

Finally, it’s incredibly easy to either list the guidance on an admin page, or generate it to static documentation during build: just enumerate the LogEvents.AllEvents property.

The Code

I’ve posted some sample code to

Something interesting things in that repository are:

  • I’ve split the ‘framework’ code like the AllEvents property into a partial class so that LogEvents.cs stays cleaner.
  • I’ve written some convention tests that cover uniqueness of ids and validation of operational guidance.

Wrap Up

There’s absolutely nothing about this solution that is technically interesting. It’s flat out boring, but sometimes those are the most elegant solutions. Jimmy already wrote about enumeration classes 5 years ago.

Remembering Why We Undertake ICT Projects

I’ve recently been reading Standards Australia’s publication HB280-2006: "How Boards and Senior Management Have Governed ICT Projects to Succeed (or Fail)"1. Just yesterday, Pat Weaver blogged some related analysis which ultimately spurred this post.

Both sources draws similar conclusions about the need to identify the delivery aspect of a project as just one component of a larger game. Ultimately, both sources then attribute this responsibility, and thus commonality of project failure, to senior management.

I particularly like this quote from section 2.2.1 of the handbook:

The case studies provide quite strong evidence, that in general, ICT projects deliver benefits by enabling process change, and project management, user support and all the other traditional prescriptions are less important than senior management support. Only senior management can resolve the political issues that arise as a result of conflicts in objectives caused by change.

Within the software development community, we almost always view software projects as changes themselves rather than simply an enabler in a wider organisational change program. While we talk about needing product owners from the business to elicit requirements and resolve implementation questions, we don’t look to them to act as a change champion in anywhere nearly as structured a way.

Food for thought: Perhaps we need to move towards reducing the number of people tasked with gathering requirements (business analysts and subject matter experts) to make way for some people to be actively pushing change back on the business? Both Pat’s post and the handbook talk about this as the responsibility of senior management, however I think they can reasonably be assisted in a structured way, similar to how we employee business analysts rather than expecting the project champion to understand and document all of the requirements.

Certainly, the measure of overall project success needs to shift away from on-time/budget/scope delivery towards an assessment of organisational change and benefit realisation. This is a core principle to any form of Lean-based delivery, however is yet to make it’s way into the world of organisations still addicted to Waterfall-derived delivery models, or in most cases, even Scrum.

Finally, it is encouraging to note that I came across Pat’s post via a discussion thread in the Australian Institute of Company Directors LinkedIn group. This is a group very heavily comprised of senior managers, and consequently a great place to see these questions being raised.

1 Warning: The publication mechanism for this handbook is positively horrible. After handing over AU$114.27 for a legitimate license, you receive it as a rights-stripped PDF, that requires a third-party DRM plugin for Adobe Reader, which only lets you open it on one computer ever, only lets you launch the print dialog once ever, prevents you from highlighting even a single word, and prevents the accessibility functions from working (in breach of the Australian Disability and Discrimination Act). To top it all off, they still feel the need to print your full license details down the side of every single page. You’ll need to be downright persistent to even make it past page 1 as a legitimate user, which is sad considering it’s otherwise interesting content.

The Checklist Manifesto: How to Get Things Right

I’ve just finished reading Atul Gawande’s somewhat self-assuredly titled The Checklist Manifesto: How to Get Things Right. Trepidatious about reading an entire book dedicated to the unassuming concept of checklists, it had slipped in my reading queue. The result was however a pleasantly educational and entertaining surprise – he’s a good writer, with an extensive repertoire of experience. There’s even three hours of flight time left for me to knock this post out.

The foundation is simple: we’ve entered an era that’s encumbered by our ability to apply knowledge (ineptitude), as opposed to lacking it in the first place (ignorance).

Half a century ago, heart attack treatment was non-existent; patients would be given morphine for the pain, some oxygen, then sent home as, what Atul describes, “a cardiac cripple”. In contrast, responders are now faced with a wide gamut of therapies and the new challenge of implementing the right one in each scenario. When they fail, beyond the obvious downsides, blame is frequently attributed to the professional who ‘failed’ to apply a body of knowledge they have been given. As this becomes an unachievable task, we need to adopt better solutions.

Without detracting from the value of investing a few hours to read the book yourself, I wanted to tease out a few of the points I found interesting. If you find these even vaguely interesting, I really do suggest that you grab a copy.

An Emphasis on Process

Atul cites that the master builder approach to construction has been replaced with specialized roles to such a degree that we really need to call them super-specializations. It started with dividing the architects from the builders, then splitting off the engineers, and so and so forth. As a surgeon, he jokes that in the medical world he’s expecting to start seeing left-ear surgeons and right-ear surgeons, and has to keep checking that this isn’t already the case whenever somebody mentions the idea.

In the advent of this, certification processes have also evolved. Where a building inspector may have historically re-run critical calculations themselves, modern building projects involve too many distinct engineering disciplines, drawing on too many bodies of knowledge, for this to be practical. We could build a team of specialized inspectors, except this rapidly becomes unwieldy itself. Instead, building inspectors have taken to focusing on ensuring that due process has been followed. Has a particular assessment been completed by the relevant parties? Did it have the appropriate information going in? Did it produce a satisfactory outcome? Great, move on.

An almost identical construct exists in Australian employment law. It doesn’t matter if somebody is completely incompetent (or inept?); you still have to follow due process in order to disengage them. Employment courts, despite already being a form of specialization themselves, are not interested in or capable of assessing an employee’s performance. They are however capable of asserting that the correct steps were followed in issuing warnings, conducting performance management, and so forth.

Here was my first face-palm moment: I’d made the mistake of considering a checklist as a list, with checkboxes. There’s a whole set of gate, check and review processes which I’ve always mentally separated from the concept of checklists. Beyond the semantics, I found this to be a valuable light bulb moment when considering some of the other ideas.


Atul’s passion for checklists comes from leading the World Health Organisation’s Safe Surgery Saves Lives program. In trying to solve the general problem of ‘how do we make surgery safer?’, the program ended up rolling out a 19-point check list, with amazing results. It’s no small feat to cause behavioural change across literally thousands of hospitals around the world.

There were actually two behavioural changes required. First, they had to get people to actually adopt the checklists as a useful contributor to the surgical process. They had to be short, add demonstrable value, and so forth.

The second challenge was getting people to talk to each other. Some of the statistics he quotes about the number of people involved in the surgical environment are amazing. One Boston clinic employs “some six hundred doctors and a thousand other health professionals covering fifty-nine specialties.” The result of this is that operating teams have rarely worked together prior to any particular case. Having clear specialities makes it functional to have an unacquainted collection of professionals achieve an outcome, however it doesn’t facilitate an environment of team work when something goes awry. Instead, these autonomous professionals become focussed-in on achieving their individual goals.

To combat this, one of the checklist points is actually as simple as making sure everyone in the room knows everyone’s name and role before the surgery begins.

Fly the Airplane

Some Cessna emergency checklists have an obvious first step: fly the airplane. While we wait for evolution to catch-up, our brains are still wired for a burst of physical exertion to combat panic. Otherwise common mental processes go by the way side and we do something stupid.

I like the simplicity of this point, and see it being useful in a operations environment.

Pause Points

In early trials of their new safe surgery checklist, participants found it unclear about who was meant to be completing the list and when. A similar problem plagues most development ‘done criteria’ I’ve worked with. Yes, everything is meant to be checked off eventually, but when?

Airline checklists instead occur at distinct pause points. Before starting the engines. Before taxiing. Before takeoff. In each of these scenarios, there’s a clear pause to execute the checklist. The list is kept short (less than a minute) and relevant to that particular pause point.

The next time I work on defining a done criteria, I think I’ll try and split it into distinct lists. These points must be completed before you push the code. These points must be completed before the task is closed.

“Cleared for Takeoff”

Surgical environments have a clear pecking order that starts with the surgeon. Major challenges of the safe surgery campaign were getting everyone to apply the process as a team, and ensuring individual members of the team were empowered enough to call a halt if something was about to be done incorrectly. To achieve this, nurses had to be empowered to stop a surgeon.

In one hospital, a series of metal covers were designed for the scalpels. These were engraved with “Cleared for Takeoff”. The scalpel couldn’t be handed over for an incision until the cover was removed, and that didn’t happen until the checklist was completed. This changed the conversation to again be about the process (‘we haven’t completed the checklist yet’) instead of individual actions (‘you missed a step’).

I think points like this are small but important. And definitely interesting.

Now, go and read the book.

The book is an extension of a 2007 article by Atul, published in The New Yorker. I haven’t read the article, but some Amazon reviews suggest it covers the same concepts with less text. Most of the book is just stories, but I found them all interesting nonetheless.

Code: Request Correlation in ASP.NET

I’ve been involving in some tracing work today where we wanted to make sure each request had a correlation id.

Rather than inventing our own number, I wanted to use the request id that IIS already uses internally. This allows us to correlate across even more log files.

Here’s the totally unintuitive code that you need to use to retrieve this value:

var serviceProvider = (IServiceProvider)HttpContext.Current;
var workerRequest = (HttpWorkerRequest)provider.GetService(typeof(HttpWorkerRequest));
var traceId = workerRequest.RequestTraceIdentifier;

(A major motivator for this post was to save me having to trawl back to my sent emails from 2009 the next time I need this code.)

Update 28th Feb 2013: Some people have been seeing Guid.Empty when querying this property. The trace identifier is only available if IIS’s ETW mechanism is enabled. See for details on how to enable IIS tracing. Thanks to Levi Broderick from the ASP.NET team for adding this.