Category Archives: Collaboration

Measure What Matters

What’s your average API response time? Do you know? Is it important to your business? What about the 90th percentile? Do response times suffer during peak demand?

Do you think about those questions? How about these ones:

How long does it take to get a software change reviewed? Do you know? Is it important to your business? Is it a bottleneck? Do reviews get skipped during busy periods?

If you care about code reviews, you should measure them. Put them on your system dashboard. They’re as much an indicator of the health of your software environment as your API response times. Minimising Work In Progress and Mean-Time-To-Release are important parts of your QA process, and making sure your pull requests are reviewed and merged in a timely fashion is a great way to improve those numbers.

What existing products are there out there to do this? Depending on the tools you use, you can probably pull out a few relevant reports. Jira is popular, and I’ve seen PMs produce some great graphs to include in their monthly management update. The problem is, the numbers you get out of these tools don’t give you direct, real-time feedback. Their very nature as longer-term averages mean they can’t represent a call to action.

Enter TeamLab

As a software shop, if the tools I’m using don’t do what I want, I have an option: build something. This is a dangerous option to have, and countless business hours have been wasted solving the wrong problems, but I really needed a nice visual prompt of how we’re doing at our code reviews in-the-moment. I also wanted a side-project for the team to tinker with new ideas for writing web applications – so even if the project didn’t turn out to be useful, the experiment would teach us something.

I had a specific technology I wanted to try out: React Storybook. This is a really nice way to visualise your React components in various different states, and I wanted something relevant to use as a demo for the team. It was very quick and easy to get up and running with a create-react-app project including Storybook, and I hacked together a quick picture of what my PR display should look like:
Storybook10PRs
On the right, you can see my quick mock-up of a board displaying ten pull requests, and the left is the Storybook control panel.

I decided it would be useful to colour-code the pull requests, and display any reviewers and approvers on the PR cards. A new PR is yellow, and an approved one is green. A PR with reviewers turns blue, and most importantly, any PR which is older than 48 hours turns red.
StorybookPRs

This was a nice little mock-up, but there was no real data behind it at this stage. Fortunately, the Git server we use has a fairly straightforward API, and so it didn’t take long to get some real data behind this component.
TeamLabPRs

It’s really easy to see when we have PRs which are starting to get stale, and need attention. Quick – at a glance, how many PRs here have been hanging around too long and need attention?
MorePRs

This has become the go-to way of seeing our outstanding PRs at a glance, and has since gone up on a big screen on the wall in our dev team office. I soon got requests for a few other widgets to go on the same dashboard, and our little side project has become a key part of our DevOps toolkit.
TVDashboard

Has It Worked?

Having those cards up where we can see them during the day has been good – but the biggest signal is during stand-up each morning. A quick glance at the TeamLab PR board has become part of the ritual, and if those cards start to build up – especially if they start to turn red – the team has a really strong signal that we’re getting behind on our code reviews.

I don’t currently have a report which tells me the Mean-Time-To-Merge for our PRs – but I don’t think I need it. Mean-Time-To-Merge isn’t as strong or immediate a signal as a pile of glaring red PR cards looming over our morning stand-up, nor does it provide the immediate sense of relief when we clear the board.

What Next?

I’m not sure what will go on the dashboard next, but I have some idea what kinds of things I’m looking for.

I need things I can measure – things I can pull straight out of an API. Things which can directly influence numbers like Mean-Time-To-Release – but I don’t want to display averages like that. I’m going to give people a dial they can turn directly. I’ll pick an angry colour like red for things which are outside targets, and nice friendly colours like blue and green for things which are on track. Once something is off the list, I’ll make it go away.

In short, I want to find things which I can measure, which team members can directly influence, and which will improve our overall quality – and I want to put them up where everyone can see them.

In Defense of Open-Plan Offices

I recently ran across an article on Quartz about why open-plan offices are bad, and I felt I had to respond.

We went open-plan about a year and a half ago, and our results have been overwhelmingly positive. However, the Quartz article cites some real studies which back up their position; we must be doing something right which other open-plan offices haven’t worked out yet.

The first thing we did right we did by accident. Our original office layout called for medium-to-small corner desks for everyone. Thanks to an ordering snafu, what showed up were largish corner desks. This mistake cost us about six work-stations, but the benefits have been fantastic. We do have our minimalists, who hide their PC under the desk and refuse to allow anything beyond a keyboard, mouse, screen, and phone to take up even short-term residence on their desk, but we also have our clutter-bugs (I’m one of those) who end up with a million things strewn about. I have enough space to keep my clutter without impacting my neighbour, which is great for both our stress levels. There is no bumping of chairs. I can squeeze three people into my corner without annoying my neighbour. Space reduces inter-personal friction, and our desk purchasing snafu saved us from too little space and too much friction.

Those of you who are used to cubicles will be wondering what I mean by “impacting my neighbour” – surely we at least have a cubicle to ourselves? Nope. Our office layout looks something like this:

Office Layout
Office Layout
Office Layout

That’s sixteen desks, arranged in groups of four. This runs counter to the traditional wisdom that your cubicles should be set up with an “officey” feel. In fact, our layout is unusual enough that I had to draw it myself – Google Image Search turned up lots of layout diagrams for private cubicles, and a few with a twin- or triple-share design, but nothing which put four desks together like this. The thick lines are partitions between cubicles: they are a little over eye-height, but the top third is glass, so you can see your colleagues in other cubicles without having to stand up. The top and left sides of the diagram are the sides of the building, with plenty of big windows and sun-shades which can be pulled down. Below the bottom of this diagram are more desks, and to the right is an open space (further right again is the kitchen). We generally put teams together: my team has the bottom-right cubicle in the diagram.

Before you object that it may well be fine for my industry, but some people need periods of uninterrupted focus to get things done, let me tell you what we do: we’re an engineering firm. We’re not all software engineers (we have environmental engineers, chemical engineers, and other sorts), but my team is all software. We found, actually, that it was the communicators who did less well in the open-plan environment, and quickly migrated to one of the few private offices we kept. If you spend a lot of time on the phone, background noise is annoying. It’s annoying for me, too, but there’s an easy solution open to me: headphones. Some of us don’t seem bothered by general office noise, but the rest of us use varying degrees of noise-cancellation, from simple earbuds to high-end Bose active-noise-cancelling headphones. I used big over-the-ear ‘phones with lots of foam for a while, but I recently switched to Sony active-noise-cancelling on-ear ‘phones (which cost about sixty bucks), and now I can’t even hear my desk phone when it rings. My usual choice of music is Enya: it’s calming and has no distracting lyrics.

So far, I’ve just talked about why our open-plan office isn’t bad, which ignores one very big thing which surprised a lot of us. Our open-plan office is good. There was plenty of opposition to the change; I myself was deeply skeptical, and spent some time wondering if “Will I get my own office?” is an appropriate question to ask when you’re interviewing for a new position. I expected open-plan to be something we could put up with, but our experience has been much better than that.

Perhaps the best thing, for me, has been the lack of interruptions. In an office, people knock on your door, or they page your phone, or they come in and just start talking: people become interruptions on their terms. In an open-plan office like ours, the headphones-on signal has become a pretty strong indicator of “I’m busy”, and people are much more likely to come back another time, or flick you an email instead. A closed door was always a negative message: “I don’t have time for my colleagues”. We used it reluctantly, and imagined people rolling their eyes as they walked past. Headphones have become a very positive signal: “I’m getting stuff done”. In fact, if I spend too long without my headphones on I start to wonder if people might think I’m slacking off.

Another great benefit has been the general office atmosphere. There are a lot more “good-mornings” as we all get in to work. There are the occasional office pow-wows, particularly on Friday afternoons when the mood is light, we’re winding down for the week, and we sit around with beer or champagne in hand chatting about our week. Team meetings have often been praised for having the advantage of putting a bunch of smart, creative people in one room – ideas will happen. We put a bunch of smart, creative people in one room, with Google and all their usual developent tools in front of them and a beverage in hand, and we do it when the mood hits. It’s infrequent; don’t imagine for a moment that we while away our days, chatting and drinking. It’s not even weekly: there are times when most of us are busy, and it gets to 6 pm on a Friday and I notice that nobody brought ’round beers, and half the office has quietly slipped away as they finished their day.

Another benefit is that the open-plan layout is much more egalitarian, and much more accepting. New staff feel like they’re part of the team much more quickly. Status-conveying corner offices are gone. It’s much easier to change desks on a whim, because you won’t suffer from people going to the wrong office until they’re used to the change. Lack of an appropriate office is no longer a barrier to promotion: we used to have a small number of cubicles in the centre of the office. You were seen as a junior until a proper office opened up and you got to leave the cubes. If the offices were all full, we couldn’t hire an experienced candidate and put them in with the juniors. Going open-plan has made some problems we used to have vanish.

I said before that the best thing has been the lack of interruptions, but it hasn’t, really. It’s been the inter-personal dialog. Not counting weekends, I spend more waking hours at work than at home, and I’m a big believer in feeling just as at-home at work as you do at home (exception: the dress code!) Switching to an open-plan layout has transformed the office from a little room where I go to work, into a friendly, social atmosphere where I can shut out the world and just get things done, or listen to my friends and colleagues while I perform less-concentration-intensive tasks.

I understand the concerns of the anti-open-planners. They feel like they’ll lose their privacy. They feel like they’ll be constantly interrupted. Worst of all, they feel like they’ve been commoditised – they used to have their own office, now they’re just another plot in a cube-farm. This feeling is partly the fault of pop-culture: it has always idolised big, well-appointed, private offices, and the cube-farm has been mocked in Dilbert so often we’ve come to believe the stereotype. The simple fact is, however, that moving from private offices to an open-plan layout hasn’t commoditised us in the least; if anything, it’s made each of us see our colleagues more as individuals, and less as office doors.

There are certainly things which can go wrong in open-plan offices, but I think, in general, that they’re not short-comings of the open-plan environment; they’re short-comings of the organisation, which closed doors used to hide. People shouting across the room or taking things from your desk is not an open-plan problem; it’s a respect problem. Disagreement on the A/C temperature? Did you honestly have individual thermostats in your offices? I never have. In an open-plan office there will probably be hot-spots and cold-spots – if you don’t like your micro-climate, see if you can swap with someone who has a location that’s more comfortable for you. I love sitting directly under an A/C outlet to stay as chilly as possible.

One thing which has been important to making our open-plan transition a success has been meeting space. We have several small rooms and one large boardroom for breaking out for meetings. One-on-one meetings with managers can still happen in private. Larger meetings or teleconferences can be held without adding to the general office noise. The boardroom has a conference phone and a computer with a huge screen and wireless keyboard and mouse. The smaller meeting rooms have desk phones and power-points for laptops. We have an office wireless network which lets people find a quiet corner with a laptop if they need to.

Ultimately, I’m not trying to say that open-plan is better than private offices. They each have their advantages. My aim is to dispel the myth that you should never put knowledge workers in an open-plan office. The Dilbert stereotype is a false one. I imagine lots of people have had negative experiences – but I’m convinced that most of those negative experiences have been the result of open-plan-done-wrong.

Here’s my recipe for open-plan success:

  • Nice big desks with plenty of power and data points
  • Freedom for people to desk-swap
  • Multi-person cubicles with low partitions between them and glass tops so you can see each other without having to stand up
  • Enough small and large meeting rooms, with computers and conference phones
  • Decent-quality active-noise-cancelling headphones provided
  • A general rule that headphones-on means “I’m trying to focus and would prefer not to be interrupted”
  • Keep a handful of small, no-better-than-the-open-plan-desks offices for those who just can’t live in the open-plan environment

If you follow those steps, you are on the right track to an open-plan layout which will be good for productivity and make your employees generally happier.

Software Collaboration using Jabber

Software teams are often not in control of their own budgets. It’s not uncommon to find teams who regularly fork out thousands per developer for Visual Studio licences, yet have trouble getting budget for a $25/year DynDNS account. I run into this sort of problem myself from time to time, and so it’s nice to have free options for key team needs.

One key requirement for a software team is to be able to communicate. Too many distributed teams rely on email and ad-hoc IM solutions, and with my current team becoming increasingly distributed, I wanted a good way for us to keep in touch. Campfire by 37 Signals is the current industry go-to option for this sort of thing, but for teams with tightly controlled budgets, or self-funded open-source projects, the $144/year entry-level plan might not be an option.

Enter XMPP.

If you don’t know what XMPP is, let me explain. It’s basically IRC with federated user account management. Is that clear? I’m going to call XMPP by its old name, Jabber, from here on in, because I think it’s easier.

Think persistent chat rooms, private messaging, moderator privileges, all of that sort of thing – but you can join any room in the world using your gmail account, or your corporate email address (if you run a jabber server), or your own personal email address (if you have your own domain). The interface isn’t quite as schmick as Campfire, but there are open-source clients and libraries, so the sky’s the limit, really.

We already did a lot of our communication using GTalk, and Google Talk works over jabber – so this seemed like an ideal option.

The first thing I needed was a private XMPP server. It seems like there are two good free, open-source options out there: Openfire and ejabberd. I chose ejabberd, because the install seemed simpler – and let’s face it, there’s no point blowing hours of developer time to save $144/year. We used a DigitalOcean VPS to host it (if there’s one thing every software team needs, it’s a linux box with a public IP address). The trickiest part was realising that I needed two different host names – an authentication server and a conference server. They both run on the same virtual server, of course, but I needed a wildcard DNS entry (if there’s a second thing every software team needs, it’s a DynDNS account). My authentication server runs on (let’s pretend our company acronym is ABC) abcim.dyndns.org, and the conference server is conference.abcim.dyndns.org – and thanks to a wildcard entry, I’m only using up one of our hostname entries.

Installing and configuring ejabberd is left as an exercise for the user – but the documentation is reasonably easy to follow, and the installation is quite straight-forward. (Pro-tip: you can add any jabber-enabled account as a server administrator. I added my gmail account.)

Once you have a Jabber server up and running, you’re going to need a client. Pidgin is the hands-down winner when it comes to administering jabber group rooms (or Adium for Mac, as I understand). I signed in with my gmail account and joined a group room called Software on conference.abcim.dyndns.org, having already set my gmail account as an admin account in the ejabberd config. Now I can invite the rest of the team to the room. While Pidgin is definitely where it’s at for setting up a room, there are other clients which can cope with jabber group rooms – Jitsi seems decent, and Xabber make a sub-par but bearable Android client (the other jabber/XMPP-enabled Android apps I’ve tried have varied from non-functional to sub-par-and-not-bearable). For any team members without gmail accounts, there are other jabber account providers out there, or you can set up your own accounts @abcim.dyndns.org using /sbin/ejabberdctl.

At this stage, we had a group collaboration server which allowed us to sign in either using our existing gmail accounts or private @abcim.dyndns.org accounts. I wasn’t prepared to stop there, however.

One team member wasn’t keen on installing a native client. I can understand that – as developers, we push our machines to the limit, and we’re naturally suspicious of installing software on our machines. Down with bloat!

Luckily, there are web clients out there. I made an account for him @abcim.dyndns.org and went hunting for a web-based client. I briefly reviewed several, but the simplest install that seemed like it wasn’t a dead end was Candy, which I hosted under Apache. I chose Apache instead of the other options because I’m super-familiar with Apache hosting, and it came pre-configured for Apache anyway. It took a little tweaking to get it hosted in the folder I wanted, but it wasn’t long before I had a web client running at abcim.dyndns.org which you could point a browser to, sign in with your @abcim.dyndns.org account, and get auto-joined to our Software group room.

Even this wasn’t enough. I didn’t just want a place where we could sit and chat. I wanted a dynamic room which reflected not only what we were saying, but what we were doing – and for that, I needed to write some software.

We had recently signed up for a paid GitHub account, and migrated our old-school SVN repo into a sparkly new GitHub private repo. The benefits of that are a topic for another blog entry, but I promise you it’s been more than worth the seven bucks a month. GitHub have a great API, and part of it allows you to register for http/JSON notifications of various events, so I decided we should have notifications of various GitHub events posted to our jabber server. If you go into your GitHub repo settings and click on Service Hooks, you’ll see there’s a pre-built jabber hook – but it only accepts a username. I didn’t even try it out, but I assume it just sends event notifications to a jabber user – and I wanted it to go to our group room instead. Luckily, GitHub provide a generic WebHook option which allows you to receive JSON event notifications at your own web service.

Enter GitHub-XMPP. Well, actually, that didn’t exist a few days ago – but I realised I needed something which could accept GitHub event notifications and post them to our jabber room, so I wrote one. It was quite a fun little project, actually. On the way through, I discovered that the GitHub event JSON was woefully undocumented – and I also discovered json2csharp and json formatter and validator, which were both invaluable when exploring the json API and building a C# json deserializer. I’d also been meaning to take a look at Nancy, and this was the ideal opportunity.

The long and short of it is I now have an application (which I’m running under mono on our linux server) which can receive GitHub events and give our jabber group room a running commentary on what’s going on with our GitHub private repo. Push events, wiki updates, pull requests, issues – you name it, whatever’s going on, our faithful jabber GitBot tells our Software room what’s going on. I won’t cover the installation here – there’s a quickstart page on the project wiki.

I have plenty of plans for GitHub-XMPP – I want to turn it into a fully-featured, configurable, scriptable jabber bot, capable of being both a useful tool and a creative outlet for our team. For the time being, though, it’s functional – it serves the purpose of turning our fledgling jabber server from a place which shares what we’re saying into a place which also shares what we’re doing. GitHub-XMPP currently has somewhere between 15 and 20 hours in it – which means it’s already cost a great deal more than the $144/year we’re saving by not subscribing to Campfire. I built it on my own time, though, and not only did I have fun, I released it under the GPLv3 – so hopefully that $144 will be saved over and over, by teams with tight budget controls and open source projects.

I would encourage you to think about Campfire though – I haven’t used it myself, but I’ve heard so many great things about it I can’t wait to try it out. GitHub are using it for their internal team communication, and there aren’t many companies out there with a better finger on the pulse of modern software development than GitHub.

Please tell me about your own collaboration solutions, or if I helped you – I’d love to know I’m helping to keep other teams in touch and motivated!