Anna Shipman : JFDI

How to blog

16 September 2016

Someone recently asked my advice on blogging, particularly how I decide what to write about and whether I set aside specific time. Here’s what I said.

Share what you learn

This is my guiding principle, for blogging and otherwise. Anything you’ve learned is worth writing up, as someone else will then be able to learn it too. Writing it up also helps make sure you really understand it yourself.

Write about things you are asked about

If someone asks you for information, or you find yourself sharing the same information with different people, that could be worth writing a post about.

One of my most popular posts was one which mainly just links to other resources. I recently discovered that it had even been linked to in the call for papers for Web Directions Australia. It was basically the blog post form of an email I’d sent several times, trying to persuade people to submit to a conference.

Write about things you want to remember

I don’t have a very good memory, and one of the strategies I use for remembering things is to write them up. I have often referred back to posts I have written myself, for example on regex, on setting up a local wifi and on Git.

This helps build up a body of work, and also helps you to be less perfectionist about what you post. And it’s also very useful when you want to refresh your memory!

Write about things people ask you to write about

Sometimes people suggest you write a post about something you’ve explained to them or discussed with them, as the excellent Martin Jackson did for my post on how to raise good pull requests. I’m really glad he made that suggestion as I’ve seen that shared several times since (often in PRs).

If someone suggests you write a blog post about something that’s always a good hint as it means you’ll have at least one reader!

Don’t be perfectionist

Before I started blogging, I worried for quite some time about what I would say, how I would know to write about, or whether it would be interesting. In the end I decided to just go for it (hence the name of my blog).

My early posts are really very boring; they were just details of me getting to grips with Unix. I doubt anyone read them. But it got me started, and it got me into the habit of writing things up and speaking into the void.

The more you write boring posts, the more you think of how things can be interesting. Don’t wait for ideas to be good enough.

You could try being disciplined about a schedule

Having a set schedule can help. For example, the excellent Cate Huston posts every Monday, Wednesday, Friday and Sunday. She points out that this means you get better with practice, and also, treating the schedule as more important than the content avoids you making the wrong decision about what will be interesting to other people. (That whole post is useful advice on how to maintain side projects.)

The inspiring Mark Needham started his blog by committing to write a blog post every day about one thing he’d learned. He didn’t manage it every day, but over seven years he has managed more than one every other day.

Write the post when you get the idea

However, I don’t have a schedule. My aim is just to keep my site roughly up to date, which for me means I start to feel anxious if I’ve not posted in the past three months. I usually try and write posts when the idea strikes me and if I’ve been writing a lot, I might park it to post later.

For example, I wrote the first draft of this in August 2015, but I had just posted on the GDS Technology blog and I knew I had two more GDS blog posts coming soon, so I parked this one.

Writing a draft of it then was very easy, as I’d just had the conversation offering advice so it was all fresh in my mind, and it was easy to redraft it last night as the meat of it was all there.

Structuring your post

How to write is a whole nother post (/book) in itself but three things I bear in mind are:

You’ll get into the habit

Once you get into the habit of blogging and figure out your own style, you start to recognise what things can be formed into a blog post as they are happening.

For example, I’ve written up discussions at conferences, advice people have given me, work I’ve done and work I plan to do. It’s not all freeform discussion of why roofing should be more like software development.

The executive summary

If I could only give you two pieces of advice, I’d say: share what you learn, and JFDI.

Making my site look better on small screens

04 July 2016

I’ve had this blog for five years, but I’ve only recently started using my phone to browse the internet, at which point I realised it displayed terribly on a small screen. It’s a wonder anyone ever read my posts.

Screenshot of site on an iPhone before redesign

As a predominantly back-end developer, it wasn’t immediately clear to me what I needed to do to improve matters, so I thought it was worth making a note here once I figured it out.

Responsive design

You want the site to respond to information about the client accessing it to display in the best way for that client. In this case, I wanted the site to respond to browsers with a smaller screen and display differently, rather than just show everything as per a desktop browser but just much, much smaller.

The media query allows the site to get the capability of the device.

Redesign required

The first thing I needed to do was work out how I wanted the site to look on a mobile device, which actually took a bit of thinking about. I realised that the current layout wasn’t going to work well and, as is often the way of these things, probably already wasn’t working well.

I was using a three column layout. However, on some pages the right column was left blank, and on one page I was instead using a two column layout. Only one page was making full use of the three columns. It was time to let it go.

Only page using 3 columns Page using 2 columns

Redirecting a URL

I took that opportunity to also rename the Games page. I used to spend more time developing little games; now I do a more diverse range of side projects so I can showcase more of that here. Because my site is hosted on GitHub pages I could not do a 301 redirect, but I set up a meta refresh tag to redirect to the new page. A 200 to a 200 is not ideal, but is better than a 404.

You can see the redesign changes I made on GitHub.

Use Jekyll for the whole site

When I originally started this blog I handcrafted the HTML for each post, and the rest of the site was also handcrafted HTML. My principle was just to get started rather than waiting until I’d figured out the best way to do it.

When I started using Jekyll, I only used the Jekyll features for the blog. However the redesign from the inconsistently applied three column layout made it much easier to Jekyllise the whole site and allowed me to remove a lot of the duplication and handcrafting.

These initial changes actually made the site worse on mobile because there was more padding on the right.

Screenshot of site even narrower on iPhone screen

Set viewport

The first change after the redesign was to add the viewport meta tag with an initial scale of 1. This sets the zoom level at 1:1 so the page is rendered at the width appropriate to the device width rather than zooming out to fit the whole page onto the screen.

Make embedded video responsive

After setting the viewport initial scale, most individual posts looked good on mobile. However the JDFI page has all the posts on it, and it looked very wrong. All the content was squished to the left.

JFDI page with all content squished to left

It turns out that the code provided by YouTube and SlideShare to embed videos/slides into your site is not responsive; it has a fixed width. This means that the site renders the text correctly for the size of the device, but when it gets to the fixed width video it then zooms out to allow space for it.

An embedded video pushing the page size out

These two articles were useful in working out how to fix this. I changed the HTML to not have the fixed sizes and added some CSS.

It also turned out that on Safari (and hence on the iPhone) long lines of code were not broken, leading to the same effect as the fixed-width video, which I fixed with an addition to the viewport tag.

Only have two horizontal columns if device is large enough

Once I’d done all this set up I was at the point I needed to be, where I could change the layout based on the size of the device.

To do this, I looked through the CSS for anything that changes the horizontal structure of any of the elements, e.g. width, float etc, and put that inside a @media query block. Initially this was just the two columns but I later added the Twitter link.

Move columns into preferred order

After all these changes, I then changed the HTML to make the columns appear in the order I would like if they cannot be side by side.

There are many other improvements to make to this site but hopefully if you are reading on mobile it’s much easier. Do let me know!

Useful questions for one-to-ones

30 March 2016

When I started line managing people at work, three years ago, I got some great advice from the excellent Andrew Seward. He structured one-to-ones around the following list of questions:

  1. How's it going? (they always say 'fine')
  2. How are you feeling about the work the team's been doing?
  3. Of that work, how are you feeling about the parts you've personally been involved with?
  4. Do you have everything you need to do your job? (important one!)
  5. Is there anything you’d like from me that would help you do your job better?
  6. How is ${new person} doing? (if they have a new team-mate)
  7. Have you had a chance to work with the others in your team? How has that gone?
  8. How have you been getting along when working with other teams within development?
  9. How about when you've had to deal with other parts of the company? How did that go?
  10. ${offer some feedback – always some positive and some negative if necessary}
  11. Is there anything else you wanted to raise?

When I started out I didn’t try and subtly steer the conversation to cover these areas, I just explained what I was doing and then went through the questions one by one. It became more natural in later one-to-ones, but even just going through the questions in a very structured way sparked discussion and brought out issues that might otherwise not have come up.

All of my reports who have since taken on line management duties have asked me to share this list, which suggests that it was a useful tool for them too. I’d be interested to hear similar questions that have worked in your one-to-ones.

Code sharing in large organisations

24 March 2016

At Scale Summit last week I led a session on code-sharing in large organisations. I was particularly interested in how other organisations raise the visibility of shareable code. This was one of the main themes that came out of the recent code-sharing unconference at GDS.

These are the main things I took away from the discussion. For more comprehensive notes, check out Barrie Bremner’s write-up.

Some ideas of how to raise visibility of code

People in the session shared the way they publicise code/projects in their organisation. Techniques include writing blogs, either internal or external, presenting at internal meetings and writing things up on internal forums. Facebook have a newsletter called the Weekly Push which is used, among other things, to publicise less well known features or new products. In some offices this is pinned up in the toilets!

However, apart from the last one, these are mostly pull methods of communication. You have to know they are there and how to find them. The newsletter is a great idea, but in less joined-up organisations you can’t be sure that push communications will get to everyone.

It’s useful to have a community

The discussion kept returning to the value of having a community around areas of interest. If you are regularly talking to other people in your field, you are more likely to find out about similar work other people are doing. There can be a lot of noise, and a community can help you learn what works and what doesn’t, and can make it easier to talk to relevant people at the start of a piece of work, rather than when you’ve gone too far down a certain path. In order to encourage useful sharing of information and discussions taking place at the right time, an organisation could support these kinds of communities.

As well as meetings and distribution lists, people talked about other ways to share information, for example, having a Slack channel for a particular community. You could drop in and say “I have this problem, does anyone have a solution?”.

One person pointed out that we often focus on code-sharing when in fact the real goal should be community. If code is shared or reused as a result of that community, that is good, but having a community is where the real value lies.

For those working in UK government, there are already some forums for these discussions.

How to build a community

One useful idea came from Paul Gillespie (quoted with permission). He explained that at Skyscanner, they copy Spotify’s org struture, and have something called guilds. These are essentially communities of interest. For example, they have one for web dev, one for AWS, one for Python. These guilds have Slack channels, mailing lists and every two weeks they have a guild meeting, which is a one-hour webinar. They use Trello to set the agenda for this meeting, and each guild is run by a core committee.

I later talked to Paul a bit more and he said that in total they have around 6 or 7 guilds. You don’t want to have too many, because being involved in a guild is quite labour-intensive.

Beware of premature optimisation

Early on in the discussion it was pointed out that we should be mindful of what problem we are actually trying to solve before addressing how to share code. Many problems seem superficially similar but turn out not to be, so the same code/product/solution will not be appropriate to both. You may waste time coming to this conclusion or bloat software by trying to make it cover too many different scenarios.

There can also be a lot of pressure to consolidate, and some of this can come from senior management seeing false patterns, for example “too many case management systems”. It was noted that spotting actual duplication and finding prior art in this area is part of the role of an architect, but in a large organisation visibility of code is still difficult.

The problem we are trying to solve is to reduce duplication of work, rather than specifically duplication of code. More generally, we do not want teams to waste time reinventing the wheel. We do not necessarily want “the best tool for the job”, we want the most cost-effective tool, and that might be copying someone else’s code, or the team solving the same, or similar, problem in a different way.

Code-sharing isn’t always the answer

If someone has written code that is perfect for your use case, it can still be hard to share. Even if it is well documented, there is still a ramp up cost to understanding it, and it is unusual that the code can be dropped right in. Several people mentioned that you need to weigh up the cost of these factors against the cost of duplication of code. Arrayed against these factors, building it yourself might not turn out to be that expensive.

It’s important to weigh up the costs

The general feeling was that forming a community is very useful to prevent duplication of work or code, but it was also pointed out that there are costs. For example the time cost of communication and staying in touch, keeping documentation up to date etc. Again, these may outweigh the costs of duplicating work.

There are other advantages to being involved in communities of interest, but it is worth considering the cost of the time and effort. For example, while the idea of a Slack channel for a community, mentioned above, can be very useful, Slack can also be a drain on productivity.

We also returned a few times to the topic of sharing services, or platforms, rather than the code itself. Instead of writing code to be shared, build a service or platform that provides functionality. However, the question of cost came up again: building and operating a service is expensive and takes skilled people, as well as maintenance costs.

My take-home message

The main thing I took away from this discussion is that you need to be clear about what problem you’re trying to solve and what the costs of the solutions are. Sometimes an increased awareness of code that has already been written will solve your problem, but sometimes what you need might be access to a service, or it might be to share knowledge across a community.

Thanks very much to all who took part in the discussion.

Choosing Cloud Foundry for the Government Platform as a Service

17 December 2015

We previously wrote about looking into offering a platform to host digital services. This post is about the technology we chose for the beta and how we made that decision.

Government PaaS team

Comparing technologies for the prototype

The first thing we did was look in detail at the various open source and proprietary options available. I’ve previously written about how we compared the open source options and I mentioned that the front-runners were Cloud Foundry, Deis and Tsuru.

Deis was a very good option, but we ruled it out for our prototype for two reasons: it didn’t have the granularity of user permissions we needed, and it didn’t have a mature service broker, which would allow us to connect to external services, eg Postgres. Both of these things are on their roadmap, but the timing wasn’t going to work for us. However, we had a very interesting conversation with the Deis team and this is definitely a technology to keep an eye on.

With the proprietary options, the method of comparison was slightly different because the source code isn’t available to look at, and because it’s not usually as easy to get a sample platform up and running.

There were four proprietary vendors we were particularly interested in: Apcera, OpenShift Enterprise (Red Hat), Pivotal Cloud Foundry and Stackato. Each one of the vendors answered questions to a similar level of detail as we were able to learn by investigating the open source solutions ourselves. Because of commercial confidentiality, I can’t share the detail here but it allowed us to compare the proprietary solutions, and then again with the open source ones.

They all had advantages, but the one that most suited our requirements was Apcera.

Comparing Tsuru, Cloud Foundry and Apcera

We wanted to get a prototype up and running quickly so we could start showing it to our users in government to see if we were on the right lines. So we decided to start with an open source solution because there are no licensing issues.

We built a prototype using Tsuru, because it’s easier to get started with Tsuru than Cloud Foundry. Then we used that prototype in our user research - we wanted to make sure we understood which features were most important to our potential users.

We then built another prototype in Cloud Foundry to compare its features, ease of use and maintenance requirements to those of Tsuru. Simultaneously, we spent some time exploring a trial installation of the Apcera platform with our engineers providing feedback about each of the three different options.

Why we decided to go for open source rather than proprietary

Paul Downey, the product owner on the Registers team, has described the work we’re doing on Government as a Platform as fitting into three categories: product, platform and standard. Product, platform and standard sketch by
@psd

Licence: Creative Commons Attribution Paul Downey

This is how we apply those categories:

If the technology we choose is not open source, the product would be the proprietary option. So in effect, we’d just be recommending a product to other departments, and they would then have to build their own platform and incur costs over and above supporting and developing the platform. But having the code available for use by other departments as a platform would encourage collaboration with our colleagues in those departments.

Using an open source solution brings a number of other important benefits. The chance to contribute code upstream means we can help make the product useful to us and others in a similar position. Maintaining and building open source components and the ‘glue’ (ie the code required to keep it all together) builds skills and learning in-house. And it also echoes our tenth design principle: ‘Make things open: it makes things better’.

Choosing Cloud Foundry

The three technologies we looked at in more detail had a lot to recommend each of them.

Tsuru:

Cloud Foundry:

Apcera:

While each of the technologies we looked at had advantages, the open source requirement is important to this project, so we had to rule Apcera out for now.

It was a very close contest between Tsuru and Cloud Foundry. After a lot of consideration we chose Cloud Foundry for our beta. The maturity of Cloud Foundry, as well as the size of its community, were the most significant factors in this decision.

However, all three technologies are very good and if your team’s requirements are similar to ours then it’s definitely worth considering them all.

Next steps

We hope to share more detail about what we learned about each technology in future posts, but in the meantime we’re now starting the beta build using Cloud Foundry. We’re coding in the open, and aiming to be hosting live services early next year.

This post originally appeared on the GDS Government as a Platform Blog.

Video of Operations: a developer's guide

27 November 2015

Video from my FFconf talk Operations: a developer’s guide.

Slides and links in previous post.

Slides and links from Operations: a developer's guide

07 November 2015

Slides from my talk Operations: a developer’s guide, at FFConf 2015.

The last slide is links; these are copied below so you can actually click on them!

Video to follow…

Configuration management

https://www.scriptrock.com/articles/the-7-configuration-management-tools-you-need-to-know

http://gettingstartedwithchef.com/first-steps-with-chef.html

https://docs.vagrantup.com/v2/getting-started/provisioning.html

Virtualisation

http://searchvirtualdatacentre.techtarget.co.uk/definition/Virtualisation

http://searchservervirtualization.techtarget.com/definition/server-virtualization

http://www.infoworld.com/article/2621446/server-virtualization/server-virtualization-top-10-benefits-of-server-virtualization.html

Using Vagrant

https://www.vagrantup.com/

http://blog.bennycornelissen.nl/otto-a-modern-developers-new-best-friend/

https://github.com/patrickdlee/vagrant-examples (Useful getting started examples)

Docker

http://patg.net/containers,virtualization,docker/2014/06/05/docker-intro/

https://zeltser.com/security-risks-and-benefits-of-docker-application/

Containerisation vs Virtualisation

http://www.slideshare.net/bcantrill/docker-and-the-future-of-containers-in-production

https://www.scriptrock.com/articles/docker-vs-vagrant

Make instead of Grunt/Gulp

http://blog.keithcirkel.co.uk/why-we-should-stop-using-grunt/

https://www.youtube.com/watch?v=0RYETb9YVrk (Talk on using NPM as a build tool)

https://blog.jcoglan.com/2014/02/05/building-javascript-projects-with-make/

Tools for better dev

http://www.leancrew.com/all-this/2011/12/more-shell-less-egg/ (More detail on the 6-line Unix program)

A PaaS for Government

29 October 2015

I gave a keynote at Velocity EU about the work I’ve been doing on a PaaS for government.

Looking at open source PaaS technologies

27 October 2015

I’ve been working on a prototype of what a Platform as a Service (PaaS) for government might look like, as we wrote about in a previous post. One of the first things we did was look at the open source PaaS options that were available. This post is about how we did that and what we learned.

Comparison table of PaaS

The open source options we considered

We looked at a range of proprietary and open source options. In this post, I am focusing on open source. This is because much of the information we learned about the proprietary options was shared in commercial confidence. I’ll talk more about the proprietary options we considered and how we compared them in a later post.

Exploring the options

PaaS is a very fast-moving field at the moment and there are a lot of options. The first thing we did was take some time individually within the team to identify which options were worth investigating. We based that on previous experience, things we’d read about, and further research online. We were around eight people on the team, so we had a lot to draw on.

It’s not always the case that you are comparing like-for-like with PaaS technologies. For example, Cloud Foundry is a fully-featured PaaS, whereas Mesos is a cluster-management system. While Mesos on its own has a number of PaaS features, it didn’t meet a combination of the criteria "developer self-service" and "multi-tenancy" (e.g. no authentication, access control).

I wanted to investigate Mesos as it’s an interesting technology, so we looked at ways to combine it with other technologies who offer those features. We chose combinations of technologies based on what we found to be common combinations. In this example, you can see we looked at both Mesos + Aurora, and Mesos + Marathon + Chronos (Mesosphere).

At this stage, we ruled out things that we didn’t think were worth investigating further (for example, they were nowhere near production-ready) and worked out some combinations that made sense to look more into.

The longlist of technologies we investigated is:

Our selection criteria

In our previous post I outlined the four main criteria we’d identified from our user research: a PaaS would have to be multi-tenant, self-service, allow application developer support and be able to run on multiple public clouds. This had already allowed us to rule out some technologies (for example, a number of PaaS technologies only run on AWS). We also had some further must-have criteria. The complete list of our selection criteria is below:

Must haves:

Investigation points

Brett Ansley, our business analyst, wrote these up very clearly and with acceptance criteria to clarify what we were looking for. For example, for zero downtime deploys:

Given: an application that is receiving requests
When: a new version of the application is deployed
Then: there is no downtime of the application.

Comparing against our selection criteria

We then split into pairs and each pair took a technology in turn to evaluate it. Dan Carley, our tech lead, outlined some consistent steps to take in each investigation so that we could be sure each pair was investigating in the same way. For example, to investigate high availability:

Each pair spun up the technology they were using and investigated it. As they found the answer to each of the selection criteria, they marked it on the whiteboard (main photograph) so we (and any passers-by) could clearly see how we were progressing and which technologies had what. If any technology failed a must-have, the investigation would stop; otherwise it was time-boxed to two days.

Multi-tenancy

The overview of what we learned about each can be seen from the photograph of the whiteboard above, and is summarised in this spreadsheet. It’s worth noting that the spreadsheet is slightly more up-to-date than the photograph of the board; for example Rancher and Tsuru were late entries, and some answers were updated with more information that we learned later.

One thing that I found particularly interesting was that multi-tenancy is not a feature of many of these technologies. For example, Kubernetes and Mesos, two widely used and interesting technologies, do not support multi-tenancy. There’s no way to ensure that a team of developers can administer only their application and not the applications of another team. This meant that they were not suitable for our purposes.

The tech that meets our needs

After going through this process of looking at and comparing a number of open source PaaS solutions, the clear front-runners were Deis, Tsuru, and Cloud Foundry. The next stage was to investigate these three technologies more and choose one to build a prototype. This has helped us with user research, which we'll share more on later. In the meantime, we hope sharing what we’ve learnt about these technologies is useful to you, and do let us know your thoughts in the comments below.

This post originally appeared on the GDS Technology Blog.

Building a platform to host digital services

08 September 2015

Right now, hosting services is one of the most time-consuming barriers for new digital services, and usually involves duplicating work done elsewhere. On the Government Platform as a Service team we’re working on solving that.

Repetition, repetition, repetition

Every digital service that government runs needs to have a place to run from; it needs to be hosted somewhere so that it is accessible to users via the internet. The service doesn’t ‘just work’; there is a lot of effort involved in setting up all the components required to host a service.

These components don’t vary much between services. Every service needs an automated way to let developers know when something is wrong, or to alert them to something. So, in practice, these groups of components end up looking very similar across very different services. The picture below shows you an example:

image showing three projects with the same technical stack, including alerting, monitoring, logging, each running on a cloud provider

As you can tell, there’s a lot of duplication. Teams all over government can end up duplicating work that’s already been done elsewhere. That means spending time on areas that aren’t their speciality, such as application monitoring or log aggregation, which stops teams from focusing on their areas of expertise.

It also leads to a lot of time searching for people with expertise in this area to hire. All of this takes time and money and leaves teams less time to focus on their users’ needs.

One way to address these issues is to provide a platform as a service (PaaS) that services could use for their cloud hosting. A shared PaaS would then change the diagram above into something more like the one below:

image showing three projects, each running on Government PaaS, which has a technical stack including alerting, monitoring, and logging, and running on three different cloud providers

A Government PaaS wouldn’t just solve the issue of duplication, and where to focus your teams. One thing that takes a lot of time in government is procuring commercial services and making sure they are accredited. If we could do that once, for the PaaS, then that could save service teams a great deal of time, while making sure that those aspects are being handled in the correct way.

What a Government PaaS needs

From the user research we’ve been doing it’s clear that it’s important that our platform has a concept of multi-tenancy - applications that run on the platform should be isolated from each other and not be able to read or change each others’ code, data or logs. It wouldn’t be appropriate, for example, if the Digital Marketplace application was able to access the data of the GOV.UK publishing platform.

We’ve also learned from our experience supporting GOV.UK that a platform where the people developing applications also support the application out of hours leads to better software and a better user experience. We want a platform that supports this model right from the beginning.

Apart from multi-tenancy and the support model, there are some other things that we feel are important in a shared PaaS.

It needs to be self-service. It needs to be easy and quick for application teams to get started, and the teams using the platform need to be able to make frequent changes. That means we need to make sure applications can be deployed and managed by the application teams, but also that they can make other administrative changes to their applications, for example configuring DNS. Allowing teams complete control of their applications will remove any unnecessary delays for them, and means the platform team can focus exclusively on iterating and improving the platform itself.

It needs to run on multiple public clouds. This approach ensures that we avoid being locked into a single provider, so we encourage price competition, while also removing the risk of a single point of failure. Changing infrastructure providers is very difficult to do if you’ve built to a single provider’s specification so this needs to be built in from the beginning.

What we've been doing

We’ve spent a couple of months exploring what a Government PaaS might look like and how it could help teams running digital services across government. We’ve spoken to many potential users, and we’ve worked closely with our colleagues in other departments who are working to address similar problems, and we’ve found that no existing departmental solution meets all the needs we’ve identified.

We’ve evaluated several open source and commercial options, and we’ve built a prototype and shown it to potential users – developers, web operations engineers and services managers – both within GDS and in other departments. We’ve tested our prototype by seeing how it works with real applications (for example, we tested it using Digital Marketplace and GOV.UK’s Government Frontend).

We’ll write about all of this more in later blog posts.

What we're doing next

We expect to be in alpha until the end of November, by which time we will have completed a detailed comparison of two open source PaaS technologies and addressed issues around performance, security, and scalability, for example. We are really interested in talking to more potential users, so if you are interested in getting involved in our user research, or seeing a demo of what we’ve done so far, please get in touch.

This post originally appeared on the GDS Blog and was co-written with Carl Massa.

A career path for technologists at GDS

24 July 2015

Until recently, career development for technologists at GDS was relatively unstructured, and dependent on what opportunities came up. Over the last few months I’ve been leading on developing a more structured career path for developers and web operations engineers. This blog post describes what that involved.

Working out our values

First, we needed to be clear on what skills we expect someone to demonstrate at each level (e.g. junior, senior). Every organisation has implicit cultural values, and we wanted to draw these out as well as technical skills, so it’s clear what behaviours we want to reward at GDS.

It's really important in government that people are well rounded, for example having the skills to share externally the things we do at GDS, having an ability to coach and lead colleagues. Making these things explicit is an important part of the exercise, and is one reason why it’s hard to take a career path from another organisation – their values might not reflect yours.

To identify these skills and values we held a series of facilitated workshops with a group of people from our technology community. In order to involve more of our technologists, bob walker, Daniel Roseman and Tom Byers gathered feedback between the workshops from others in the web operations, backend development and frontend development communities.

We also decided at this point that there shouldn't be a frontend/backend distinction; many of the skills are the same, and we want to encourage people to work across the full stack.

Adding more technical skills

The workshops produced an outline of what skills were expected at each level. However, it was quite light on details of technical expertise. It's harder to work that out by committee.

Myself, Brad Wright and James Stewart – three technical architects who are also senior line managers – listed the technical competencies we expect at each level. We also talked to line managers to see how what we had come up with fitted in with how we were already working on developing people.

At this point we had an alpha version of the career paths document, definitely not formatted as we would like, but with the information we had learned in it. You can download the first version as a PDF: Developer:web op career paths v1.0.

Use of the career path

The main aim of the career path work is to help people clarify where they are in their careers and what to focus on when working out how to progress, so the way the document is meant to be used is in a conversation with your line manager to talk about where you want to get to, and what practical things to focus on to help you get there.

The conversation focuses on the four skill areas: technical expertise, delivery, digital evangelism and leadership. So for example, you might be a developer, with technical skills at a senior developer level, but weaker on evangelism and leadership. If your goal is to get to senior developer, we would work out some objectives that would help you develop in the evangelism skill area (for example, blogging, speaking at events) and leadership (for example being a tech lead, line management, or owning a non-technical project).

Too much information!

Once we had version 1.0 of the document, the next thing to do was use the tech line managers as guinea pigs. I pitched the work so far and the conversation template at a meeting of the tech line managers (there were about 18 at the time) and asked them to go through the process with their own line managers and let us know how it went.

This process of user-testing was very useful and we learned a lot.

For example, one thing I had tried to make very clear was that this is not meant to be a tick-box exercise. It should not be the case that if you can show one example of each skill at each level, you automatically progress to the next level. The examples are meant to be an indication of the sorts of things you can be expected to do.

However, including so much detail at each level made it very hard to not do it as a tick-box exercise. Contrary to what we had expected, we needed to include less detail, to make it clearer that they were examples.

It was a useful framework for working out specific areas of development

One important thing we discovered was that even though the document itself still needed further development, the conversations using it were some of the most constructive and useful line management conversations we’d had so far.

I line manage four people, and all four of them came out of our conversation with useful, practical development objectives that they were able to immediately start working on in order to develop their careers as a technologist within GDS.

It’s still a work in progress

We’ve made some changes based on the feedback from the tech line managers, and with input from James Holloway, then a writer at GDS, we produced the next version, which you can also download as a PDF: Career_pathing_for_technologists_v2.0. We’re now using it, and all technologists at GDS have had an opportunity to work out their career plan with their line managers. There are still many areas for improvement, and Alice Bartlett, Edd Sowden and others are currently working on the next iteration.

One interesting point is that we may have gone too far the other way on removing detail. I suspect the way to balance this will be around how we communicate the process, rather than reaching a genuinely “perfect” amount of detail (this is another reason this document may not, as it stands, work for your organisation).

There are also several areas we didn't touch on and will have to be addressed in future. For example, this is not currently related to salary. The career development conversation with your line manager is about where you sit at the moment, where you would like to get to and what steps to take to get there, purely from a skills and career development perspective.

In addition, at the moment this is separate to the annual review process, though the areas for development identified here are really useful for working out development objectives for the annual review process.

It’s definitely been worth doing

Working out our career paths has been a really useful process and we are now doing it for other roles, such as delivery managers and designers. One important thing we’ve learned is that while the finished artefact is useful, the process of how you create that artefact is more important. It has to reflect what you value as an organisation, and this process forces you to be clear about what that is.

GDS started in 2011 with a small team of 12 people, and then grew very rapidly until we numbered 600 in 2014. When your organisation is first getting established, things like structured career development are rarely the top priority. Now we are maturing and people are thinking about staying on for some time, it’s critical to make sure we put these things in place.

This post originally appeared on the GDS Technology Blog.

Tips on writing a technical CV

19 July 2015

In the last few years I’ve been more involved in recruitment and seeing a lot of CVs for developer roles has given me some thoughts on what makes a good technical CV. Here are some tips to improve yours.

Make it relevant!

What I want to know when looking at a CV is whether you have the skills I’m looking for, and if not, whether you show the potential to gain them. I want to know what technologies and practices you know, and what you are doing at the moment. Ideally I’d like the two to be related – if I’m hiring for a Ruby developer (we’re not at GDS, we want good developers of any discipline) I want to know if you are going to hit the ground running.

So when you are describing your current or recent roles, make sure you highlight the things you are doing that are relevant to the job that you are trying to get. For example if the job spec asks for experience of leading a team, then make sure there is evidence for this in the description of what you’ve been working on. Use your cover letter or statement of suitability to draw attention to these areas. Make it easy for the hiring manager to see that you tick all the right boxes.

Together a CV and covering letter should leave no doubt that you know what is wanted and that you can provide it.

Address gaps and concerns

When you are reading a CV you notice gaps and short jobs, particularly recently. The good CVs are ones that address these rather than brushing over it. For example, one CV I saw, their most recent employment was two years ago. Had they been unemployed since then? No – they had taken some time out to raise a family. Another one had only been in their present job for three months. Why were they leaving so soon? They covered this in their letter – unfortunately the company was changing direction due to cash-flow problems. That’s fine – some of the best people get made redundant. But if you don’t explain, it invites the reader to wonder if you failed your probation, or if you changed your mind about working there and might change your mind about working here.

View anything like that through the eyes of the recruiter and offer an explanation, rather than attempting to gloss over it.

It’s also worth addressing any gaps in the required skills. In the example above, if you can’t provide evidence of team-leading from work, can you give other evidence, for example from captaining a sports team or running a Brownie pack?

Do what they asked for

Make sure you supply the requested information. In my case, I was reviewing CVs for a job as a developer at GDS. Our process has now changed but at the time our job adverts said that in order to apply, you need to send “a CV, a CV cover letter, and a written statement of suitability explaining how you meet all of the competencies and specialist skills required”.

A very large number of candidates do not include a written statement of suitability. This is an unusual requirement, but in the civil service it is an extremely important one because if you do not demonstrate evidence of the civil service competencies at some point in the process, we are not allowed to employ you.

OK, so this may not seem very relevant if you’re not thinking of applying to the civil service any time soon. But it is. As a developer, you want to demonstrate that you are able to understand users’ requirements, and a good place to start is with what they actually ask for.

Sell yourself

Essentially that’s what your CV is: a document for selling your skills. So make sure it does that. Say what you have done. Don’t say “I was asked to…” or “My team were given the task of…” Instead, make it clear that you actively seek out and take opportunities, rather than just being handed them.

It can be quite hard, as many of us are naturally quite modest, but it’s good to make it clear that you are a self-starter. It’s also worth phrasing things to show what your contribution to a team’s achievements were. I am interested in what your team achieved, but I am not hiring your team, I’m hiring you, and I want to know what you did to help the team reach those goals.

A profile can be useful

One thing that I find quite useful when looking at CVs is a profile at the top. Just a couple of lines that sum up your current role and what you’re looking for. It’s not essential, but it gives me an overview of what I’m going to read below and whether this person is likely to be a good fit for the role.

You don’t have to say everything!

I don’t really need to read four pages listing every job you’ve had since 1999. What I’m interested in is what you can do now. I want the current/most recent job, maybe the one or two before that if you’ve not been at your current place for very long, and if you do a lot of short contract work then maybe a bit more. And then summarise the rest – you just want to show a natural progression.

Similarly, very long lists of technologies are not that useful, particularly if they include things like SVN, Eclipse and Unix. If you are sending your CV to be included in a searchable database, for example for a recruitment consultancy, these will help, but if you are applying for a specific job, it is better to focus on the skills being asked for.

If you’ve worked on a full-stack project, you will have come into contact with a lot of technologies, and if you’re a good developer I don’t doubt you can pick up ones you don’t know quickly. Just concentrate on proving to me that you’re a good developer.

Context is useful

What shape has your experience been? A line summarising what a company’s business is and roughly how big it is is useful. Job titles in tech are very fluid and something like “senior developer” doesn’t mean the same thing from place to place. If you tell me how big the dev team is, then that gives me a bit of context.

And give details. Examples are good. You were a Linux admin; how many servers did you manage? Even better is examples of particular things you did. Don’t just say “I improved performance”, say “the site was experiencing extensive load spikes and I was able to diagnose the cause as X and implement solution Y which led to a reduction of Z%”.

Spend time on the layout

Yes, I know, you’re a developer not a designer. But get a designer to look over it if you can. Grey text, a lot of bold, tiny text – these all make it harder to read. When recruiting for the civil service we read each CV closely even if it is hard to do so, but in the private sector if your CV is too hard to read that might be enough for it to be rejected.

And be aware that it might be printed out.

A word on age

How old you are is irrelevant to how well you can do the job, and since the 2010 Equality Act it is illegal for employers to discriminate on grounds of age. So there is no need to include that extraneous information in your CV. Don’t include your birthdate. You don’t even need to include dates of your formal educational qualifications which would allow people to guess your age. And adjectives like “young” to describe yourself are also odd – you are inviting the recruiter to discriminate. Don’t do it.

In summary: make it easy for them to pick you!

It is much more cost-effective to rule people out at the CV stage than at the interview stage. It will probably take around 20 minutes for one person to look closely at your CV. But if you are invited in for interview, that’s a lot of extra investment of time on the part of the company.

Because we have a fair process in the civil service, you can be sure your CV will be properly reviewed. But the private sector is not bound by such rules. If your application is not great, it’s a much harder sell for the company to make the investment in interviewing you.

Essentially, you want to make it easy for whoever is in charge of hiring to choose your CV, because your CV is so obviously relevant to the role they are hiring for. This does mean that you have to revise your CV and cover letter for every job you apply for, but you should be used to that. You’re a good developer, so you are already prepared to do the hard work to make it simple. Right?

How to raise a good pull request

21 April 2015

On our team we always commit code using pull requests, for review by someone who hasn’t worked on that code.

I was recently pairing with the excellent Martin Jackson. He had made a change to use Librarian-Ansible to manage our dependencies; but the pull request was difficult to review because most of the changes were in one commit. I paired with him to help make it easier to review, and he suggested I write up the guidelines I shared.

Write good commit messages

As an absolute minimum, you should use good commit messages. The GOV.UK styleguide on commit messages is a very good summary of how to do this and why.

Essentially, the diff shows you what has changed, and the commit message should tell you why. Ideally, you should make the explanation of why you made that change as if you were talking to someone who is looking at this code in two years, long after you’ve moved on to another project. What may seem obvious to you now, when you are head down in that code, probably won’t be obvious to you next month, let alone to someone else later on.

Do one thing in a pull request

The smaller the PR is, the easier it is to review and so the quicker your change will make it onto master. A good way to keep it small and manageable to focus on just doing one thing in a PR. The story you’re working on might involve several changes, but if you can, it’s worth splitting them into individual pull requests.

A clue as to when a PR might be doing too much comes when you’re writing the headline for the PR. If you find yourself saying “and” or “also” or otherwise trying to squeeze in a number of concepts, your PR might be better as two or more.

Make the pull request tell a story

When someone is reviewing the pull request, it should tell a story. Take the reviewer along with you. Each step should make sense in a story of how you introduced the feature.

For example, with the Librarian-Ansible change we rebased this commit into this series of commits. Each of those commits is self-contained and comes with a commit message explaining why that step is taken. Taken together, they tell a step-by-step story of how we introduced Librarian-Ansible.

This allows a reviewer to follow along with your process and make it easier for them to think about what you’ve done and whether the changes you’ve made are the right ones.

For example a reviewer might get to the point where we configure Librarian-Ansible to use something other than the default directory and wonder whether we should instead have changed our Ansible code to refer to the librarian-roles directory. Without the separation of steps into a story, it would be difficult to see that step and wonder about the change, so that potential review point is lost.

Make it a logical story

Ordering the commits so they tell a story can be quite hard to begin with, especially if you’re not sure how the piece of work is going to play out. After a while, you will get a feel for the flow of work and you’ll have a better idea of what small chunks to commit. Until then (and even then) git rebase interactive is your friend.

Apart from making the PR tell a story, it’s worth rebasing to keep connected changes together. For example, instead of adding some commits at the end that say “I forgot to add this file” or “Also making the same change here”, it will be clearer for the reviewer if you rebase, and add those changes to the original commit to keep the narrative. I’ve often reviewed a PR and made a comment like “this change also need to be made in X”, only to find that has been done in a later commit.

The cleaner and more logical the narrative of the commits in the pull request is, the easier it is for the reviewer to retain the whole context in their head and concentrate on the important things to review.

Provide as much context as possible

Imagine everyone else on the team has no idea what you have been working on. Ideally you want the pull request notification to arrive with a full explanation of what this change is and why you’re making it, so that anyone can pick it up and review it.

Link to the story it relates to (you can also use a webhook so the story or issue is automatically updated). Point to other PRs or issues that are related. Explain what tests you’ve done, and if relevant, what the reviewer can or should test to confirm your changes.

The more context you can provide, the easier it is to review which makes it more likely to be addressed quickly.

Make sure the pull request, when merged to master, is non-breaking

Ideally each commit should be an atomic, non-breaking change. This is not always possible. However, a pull request is a request to merge your code onto master, so you must make sure that it is complete, in that it is a non-breaking change. It should work, and the tests should still pass once your pull request is merged.

Never commit directly to master, no matter how small the change is

This is a rule on my team, for two reasons: communication and review.

When you have a number of people working on a codebase, you want to communicate to everyone what changes you are making. Raising a pull request is a broadcast to everyone watching that repository so even team members who have not been involved in that piece of work can keep an eye on what’s going on so that changes do not come as a suprise to them. You also do not know what everyone’s experience is, and raising a pull request can sometimes trigger useful input from an unexpected source; committing directly to master would have lost you that opportunity.

As well as making sure the whole team can keep an eye on what changes are happening, raising a pull request also allows the team to maintain a level of quality through code review. Some changes are so tiny that they (probably) don’t need a review, but by making a rule that you never commit directly to master, there’s no chance that something that should not have done will slip through the cracks.

An example of a good pull request

Take a look at this extremely good pull request raised by the excellent Alice Bartlett.

Alice did the work first, and then pulled out the changes one-by-one to a new branch to make it clear. While doing the work she refactored some code but in the final PR she has put the refactoring up front, to clear the way for the change she wants to make. This makes it much easier to review because the changes don’t then clutter up later commits. There is also a lot of detail in the overview.

Raising pull requests like this takes time, but it is really worth doing; it makes it clear for your reviewers, the rest of your team, and for the programmers who will be working on this codebase long after you’ve forgotten about the changes you made today.

Staying technical

29 March 2015

A few weeks ago I wrote a post about being a technical architect, and one of my main conclusions was that you need to stay technical. But how?

Phil Wills had a suggestion for me:

At QCon, I asked him more about this. Did he mean all recurring meetings? What about retrospectives? What about stand-ups? We ended up having a mini Open Space of our own, joined after a while by a couple of others, and then Phil proposed a session on ‘how to stay technical as a senior techie’ at last Friday’s Scale Summit. Here are some of the thoughts I got from that session.

Being interruptible is part of the job

Whether by “the job” we mean technical architect, manager, or senior developer, there was broad agreement that being interruptible is an important part of it. You are in that position because you have the skills to help others and it might be that interrupting you saves other people a lot of time. Twenty minutes of your time on a problem you’ve seen before could prevent someone else spending two days stuck down a rabbit hole, for example. So you need to learn how to be interrupted: how to minimise the negative affect interruption has on your own work and enjoyment of it.

Not losing context

A big problem with being interrupted is the loss of context, and we talked a bit about how to mitigate that. One suggestion that comes up frequently is blocking out time, e.g. core pairing hours. This may not work if you can’t always pick the times of meetings you need to attend but can certainly be useful when you can.

Another brilliant suggestion was around doing Ping Pong pairing. The reason this helps is that if you do get interrupted, your pair can carry on without you – this is not ideal, but if the interruption is unavoidable it does mean that the work continues and it’s relatively easy for you to reload the context when you return.

Other suggestions included working on smaller pieces of code, for example bugs in your issue tracker, rather than large features; and making sure that the code you write is such that you can keep it in your head. Finally, working on supporting tools that aren’t on the critical path can be a good way to keep coding without potentially blocking the team’s progress.

Staying current

Staying technical is not just about writing code, and we talked about some other ways of staying current. Some people found doing Coursera courses useful, though this does require a huge time commitment, usually outside of working hours, so won’t be sustainable for many people. Reading code, rather than writing it, was suggested, along with keeping up with what people are working on in the ticketing system.

One person talked about the company organising a regular Coding Dojo which seems like a great way to keep everyone current on what is being worked on. Another way to do this is mobbing, or mob programming.

The main way I stay current, which I don’t think was mentioned in the session, is via Twitter and some newsletters like Devops Weekly.

Leadership is not just about knowing the latest technologies

We finished up with a really interesting discussion around why we were all so concerned about staying technical, and it turned out that many of us were worried about losing what it was that had made us senior in the first place.

People pointed out that being senior is not necessarily being able to write perfectly in whatever cool new language recent graduates are using, it’s reasoning about problems. You are in a position to use your knowledge of similar problems to cut to the heart of the matter, and you can use your experience to ask the right questions.

Practical suggestions included using Socratic questioning to draw out problems people might not have thought about yet. “What do you think the solution is?” “Why?” “What would you do about X?”. You also should not be afraid to say when you don’t know, and “let’s work it out together”.

But for me, the take-home message here was best summarised by Robert Rees, who I quote with permission: “The fear is that you lose authority as you lose expertise, but actually that’s not true: authority comes from having delivered many projects.”

I found the discussion really useful and have some practical tips to take away. It was also nice to know that there are many others facing the same issues as me. Thanks to Phil for proposing it and to all who took part!

What is a technical architect?

01 March 2015

I have wanted to be a technical architect since I started out in IT, and last September I was delighted to achieve this long-held goal. But very quickly I realised that, while it was clear to me that the role of a technical architect is overseeing the technical aspects of large software projects, I really wasn’t sure what that meant I should be focusing on day-to-day. So I turned to some of the brilliant technical architects I know, both colleagues and elsewhere in the industry, for their advice.

Being a technical architect

In my first job as a developer, several years ago, I sat down with an architect I really respected, and asked his advice on how to get there. The diagram he drew for me in that conversation is the career plan I’ve been working off since then:

But now I am here it turns out there is a lot of variance. Different technical architects do completely different things. Some are hands-on with a project or small number of projects, writing code. Some have a consulting role. Some are inward-facing to the organisation, some outward-facing.

I know that I definitely want to stay technical, so I asked specifically about that and also for more detail of what the role involves. I focused on skills over and above my previous role as senior developer; for example, problem-solving, analytical skills and being a technical authority are all part of the developer role as well. I haven’t included people’s names as these conversations all took place in a series of private chats and emails.

A tech arch does what needs to be done

One thing that came up from almost all of the people I spoke to was that the technical architect does what needs to be done to move things forward. The role was variously described as “being a grown-up”, “the project shaman”, and “the rare responsible person”.

Of course, that could also be the description of the role of delivery manager and product owner and also, in some ways, any other member of the team. So one important thing I’ll have to think about is how to do what needs to be done to get the thing to work, without taking on too much of the non-technical aspects of that.

You need to stay technical

I definitely want to stay technical, and in any case some of the people I spoke to felt this wasn’t optional – you have to stay technical to do a good job. “You need to be coding as an architect. Try and spend as much time as you can on writing code.” This person also said “when things are going right, a tech lead and a tech arch are the same thing” and recommended Pat Kua’s series on technical leadership.

Staying technical while also doing whatever needs to be done to get the thing delivered is going to be tricky. One person advised me “the management stuff can eat up all the time if you let it, so make the time to step back and plan or engineer situations that will force you to do some ‘maker’ stuff.” One suggestion was that in a situation where I am overseeing a number of projects, I could go and visit one of them and then spend the rest of the day coding in one of their meeting rooms.

Someone also suggested that it’s good, if you can, to avoid regular, fixed commitments: “if you have a lot of steady state commitments, your ability to spend time on the most pressing issues tends to be squeezed.”

More specific than staying technical is actually trying to make sure you take the time to work alongside the people actually doing the work. One person who had done some job-hopping from technical architect to developer and back said that one thing the job changes had reminded them of is “how frustrating it can be working at the developer level with decisions being made ‘elsewhere’ in ‘smoke-filled rooms’. Working at that level a little may help you to keep in touch with these sort of issues”. Though you have to take care that people don’t treat you with kid gloves.

Responsible for communicating and enabling the technical vision

There were a lot of useful general comments on what the core skills of a technical architect are. It’s about owning the overall vision, establishing a common understanding of what the team is aiming for, and communicating it.

The technical architect should be paying attention to whether we are building the right thing, the right way, and the long-term vision. This might involve requirements, and it might involve a roadmap, but ultimately, the architect – as one person put it – should be “fundamentally lazy”; an enabler. Not command and control; rather communicate the long-term vision and let the team figure it out.

And the most important skill of a technical architect is the ability to find simplicity in complexity.

Influencing people

Many people point out that a technical architect’s role includes influencing people. As in a tech lead role this may well include stakeholder management, persuasion, and and maybe even convincing people to make big changes in the way they work.

One person had some very practical advice on this: “A conclusion from my initial architect days was that influencing people and coaching them is a major part of the job so I needed to work on it. The former doesn’t come naturally so I still have to make a conscious effort to take opportunities to talk to people without a specific purpose in order to form a relationship that will help us work together better later. People are far more of a challenge than computers! As someone said recently, if you’re looking for a complex adaptive system to work with, try people!”

Say no to things you really want to do

One skill that I’ve had to work hard to develop is learning to say no. Initially, you progress in your career by volunteering for a lot of things. You gain a breadth of experience, leadership skills and get to work on a lot of varied, interesting stuff. However, as people start to recognise you as someone who can get things done, you will be asked to take on more, and you need to learn to be selective in what you agree to take on so that you can properly focus your attention on the things you have taken on.

I thought I was quite good at that, but in my new role, I am going to have to take it to another level. I am going to have to start saying no to things that I really want to do. One person put it like this: “You will get lots of opportunities to do things that you would be really good at, that you would enjoy and you know that you would knock it out of the park; and you need to be able to say no to those things that don’t meet your goals.”

As a technical architect you are more in charge of your own time

Someone said “as a tech arch, you are largely in charge of your own time, so decide what you want to do and do it”. As noted above, a good thing to do is to carve out time for coding, design, or just thinking about a problem.

That doesn’t seem to reflect my current situation though. While it’s true I’m in charge of my time to the extent of how I help the team reach our goals, there seem to be a number of non-optional things I have to do in order to get there. A lot of that involves making sure to talk to people, and my days at the moment tend to be back-to-back meetings. Here is tomorrow:

calendar

And most of last week was the same.

In part, this is a function of the stage of my project is at; we’re just starting out so still need to communicate our initial goals and build the team. But I think it also indicates that there are some skills that I need to develop as a technical architect.

Luckily I have a great team and I’m confident that we can work out how to give everyone the room to do what they need to do, so my immediate next step will be working with the team on carving out the time for me to stay involved in the technical aspects of the project. I shall report back.

How we moved vCloud Tools from Coding in the Open to Open Source

19 December 2014

At GDS, most of our code is publicly available in our alphagov organisation on GitHub. We call this “Coding in the Open” rather than “Open Source”. As James explained in a previous blog post this is because for most of our software, we are not in a position to offer the support that true Open Source requires.

However, we do also have some Open Source Software, in our GDS Operations organisation on GitHub. When we started building vCloud Tools, they were “Coded in the Open”, and we wanted to make them into Open Source Software. Here are the steps we took to do that.

Ensuring the project has a long term home

For the first several months of vCloud Tools’ development, the four of us working on vCloud Tools were a separate team with a separate backlog. However, once the tools were ready to be used, we wanted to bring them back into the GOV.UK Infrastructure Team. Mike Pountney and I rejoined the Infrastructure Team with the vCloud Tools backlog, and our colleagues who hadn’t been working on vCloud Tools started picking stories up.

Initially this was mostly pair programming in order to share the knowledge. A couple of people who were particularly interested took more ownership, but everyone in the Infrastructure Team contributed, including the Head of Infrastructure, Carl Massa, who merged the change that published vCloud Tools to RubyGems.

Releasing each tool as a Ruby gem

Packaging the code as a Ruby gem makes it easier for others to get started with using each tool, using a commonly installed packaging tool. It also ensures that the code follows a relatively consistent structure. Most people used to working with tools developed in Ruby will quickly know how to install it, how to use it, and where to start if they want to make modifications.

I explained as part of a previous blog post the steps we took to release each tool as a gem.

Learning from others’ experience

We already had several Open Source projects, mostly Puppet modules and our own Open Source guidelines, but we were interested in learning from others who knew about maintaining larger projects. One of the main things I learned while talking to people with experience in this area was that when running an Open Source project, you want to optimise for bringing people into your community.

Because of that, we made some changes, one of which was to add contributing guidelines with the specific aim of being helpful to new contributors. We wanted to make it easy for people who were unfamiliar with what would be involved, so we included explicit detail about how to raise a pull request and what we are looking for. You can see from the contributing guidelines on vCloud Core that we say pull requests must contain tests, but we offer to help users write them.

To make it easier for contributors and reviewers to see the quality of submissions, we also added Travis configuration so that lint and unit tests and are run against all pull requests.

Guidelines for communication with contributors

At the same time we also set some ground rules amongst ourselves, for example how quickly we should make sure we respond to pull requests. We drew up some guidelines for reviewing external pull requests. These were on our internal operations manual, but I have now added these to our public styleguide for reviewing PRs.

Putting vCloud Tools with our other Open Source projects

As I mentioned, we have other Open Source projects in our GDS Operations organisation, and once vCloud Tools had met all our Open Source guidelines, we wanted to move the tools to this organisation.

Since there are six gems and they are related, we discussed moving them to an organisation called vCloud Tools. This would have some advantages, for example it would make it easier to add core maintainers who do not work at GDS. However, after some discussion, we felt that it was important to keep the link to GDS so that people who wanted to find out what work government was doing would be able to find their way to vCloud Tools along with other projects. This is also in keeping with what other organisations who have a lot of Open Source do, for example Etsy and Netflix.

We also created a website to showcase our Open Source, with a lot more detail on vCloud Tools.

Moving issues to GitHub

Another thing that came out of early discussions with other Open Source practitioners was the importance of public issue tracking. We had features and bugs in our own issue tracking system, but having them on GitHub issues is better for users because it means they can find them. For example, if a user experiences a bug, they can search for it and may find that we’ve fixed it in a later version or at least that we are aware of it. It also has the advantage that people might fix our issues for us!

At this stage we also added a ‘newcomer friendly’ label, for issues that don’t involve an in-depth understanding of the tools and don’t require access to a vCloud Director environment. This is to offer people an easier way to get involved in contributing.

Encouraging early users

Because we had been coding in the open from the start, we already had some early users. This was really useful, because we found they picked up things we had missed. For example, people coming to the project for the first time will notice onboarding details that you may have forgotten, and can help you clarify your documentation.

Users of your software also help by finding issues that you might have overlooked. For example, one of our early users noticed a discrepancy between our documentation and our code which turned out to be a bug. This was really useful because the bug was in a feature that we don’t use on GOV.UK, so if they had not raised it, we might never have noticed it ourselves.

In order to encourage users, we visited and spoke to teams both inside and outside government. This early contact helped us make sure we were focusing on features that would be useful for more than just ourselves, and in some cases our users even added these features themselves.

Sharing our experience with others

We’ve worked closely with some of our colleagues in government, and currently teams at the Ministry of Justice, HMRC and DVLA as well as external companies are using vCloud Tools for some of their provisioning.

However, visiting individual teams wouldn’t scale for every team that’s interested, so in order to share more widely we started talking a bit more about what we were doing with vCloud Tools publicly. We wrote some blog posts, including a one by Matt Bostock which shows how you could use vCloud Tools to provision your environment. Matt and Dan Carley gave a talk at the Ministry of Justice, and I gave two talks at conferences.

What happens next?

We still have work to do. One thing we’ve found difficult is when a contributor raises a pull request for a feature that is not something we need at the moment. There is work involved in reviewing the code and testing it, and when the feature is not a priority for GOV.UK we’ve found that it’s hard to make a case for doing that work ahead of other things we need to do.

We are really keen to support our Open Source projects, and including contributors’ code even when it’s not something we will use immediately helps the tools be more robust and useful. We’ve discussed some ideas around this, and our current plan is to allot some time every week specifically for working on Open Source, so that those kinds of features will be a priority during that time. We will see how we get on and report back.

We’re also aware that a wider range of contributors leads to other considerations and what that means about things like how we license code is another post in itself. Watch this space, and as always, your comments are very welcome.

This post originally appeared on the GDS Technology Blog.

How do I get more women to speak at my conference?

08 December 2014

Last year I wrote about how anonymous submissions affected gender balance at SPA conference. Short answer: not hugely, but it did have some other positive effects. This year, however, we did have more women speaking at the conference than previously. Here are some suggestions for how to replicate this at your conference.

The stats from SPA

2014

8/39 = 21% of the session leaders were women.

2/14 = 14% of the solo session leaders were women.

3/8 = 38% of the people running more than one session were women.

If you compare this to the previous three years of SPA stats, this is both more women speakers and a higher proportion of the total speakers. In addition, unlike the three previous conferences I’d looked at, some women ran more than one session at the conference. In fact, three women did this.

I recently received an email from a friend organising a conference:

Hi Anna,

I'm looking for some help in getting more women speaking and participating at ${CONFERENCE}.

I've (again) promoted the Call for Speakers using (most of) the resources mentioned on the CallbackWomen site. I'm also promoting it through local women in technology groups.

I'm also using an anonymised review process and am (as always) being encouraging to first-time speakers.

Thoughts?

These are all really good things to do, and I recommend any conference organiser does the same, but I did have one more suggestion, and that is outreach.

The best speakers may not realise it

As anyone who has organised a conference knows, there is little correlation between those who are most keen to submit and those who run the best sessions.

When we announced the call for proposals, as well as tweeting it and sending it to various mailing lists, I and my co-chair set about writing individually to people we thought would propose good sessions.

One name that was suggested to me was that of Sandi Metz. At the time, I wasn’t aware that she was the author of the extremely good Practical Object-Oriented Design in Ruby, but I looked at her website and the courses she was running sounded excellent, so I emailed her in the hope that she might be available.

She got back to me, but she was uncertain about submitting to SPA. Not because, as you might think, it wasn’t a big enough deal conference for her, but because she was uncertain that her material was appropriate for the conference. I quote from her original email (with her permission):

"I hear that SpaConf is a place for leading edge, new thought, experimental stuff, and I feel like I'm doing simple, straightforward, intuitive, well-known, obvious OOP".

I wrote her an impassioned email back explaining why I thought that topic would be brilliant at SPA (for example, it’s only obvious when you know how…) and she decided to submit.

Her session got top marks from all reviewers, was one of the best attended, and when the feedback came in, was rated the highest. I went to the session and it was really excellent. And amazingly, Sandi thanked me for persuading her to attend. Later, she said “I would never have submitted to SPA; you made this happen.”

You might think someone as successful and awesome as Sandi would realise that her session would be amazing. But that wasn’t the case. She explained, “I imagine that things that seem obvious to me are already known by everyone else”. And there are plenty of other excellent people out there for whom that is also true.

You have to encourage women to submit

Women are socialised not to put themselves forward (here is a fascinating study on one way to address this), whereas men are more likely to put themselves forward regardless of competence (Clay Shirky describes this useful skill as being an “arrogant, self-aggrandising jerk”).

This won’t translate to no women submitting; many do. But it will be worth your while approaching the women you would like to submit. And not just women but other under-represented groups. People of colour, differently-abled people, really shy people, for example. People who may have bought the hype that your conference is only for the cool newness, or who lack confidence, or who aren’t going to put themselves forward for whatever reason. Don’t optimise your process for people who think they are amazing.

This is borne out by my own experience. Ivan Moore asked me seven or eight times over a series of months “when are you going to submit to SPA?” before I finally submitted my Data Visualisations in JavaScript session. It was really successful, and I have since done several other conference talks.

Don’t just look for people who are already on the conference circuit. Ask women you know, people you work with, etc. Everyone has an interesting story to tell about what they are working on, or are researching, or their hobby, or what they are expert in.

You may have to put more work into encouraging those people to submit. It was not an insignificant amount of effort on my behalf to get Sandi to submit, but it was so worth it.

You need anonymity in selection to back this up

It’s important to note that if you are reaching out to people to ask them to submit, rather than directly to invite them to speak, you need anonymity to back this up. To quote from the article that inspired me:

If you go around encouraging people that are usually under-represented at your event to submit to the CFP and promise an unbiased selection, it ensures they don’t feel that they’ve been picked because of a particular personal feature, rather than the content of their proposals.

Our process at SPA remained the same in 2014 as it was in 2013. Read my original post for full details, but submissions remain anonymous until the point a draft programme is produced.

A not-exhaustive note on how to ask

I like your work on X. Y is relevant to our attendees. I saw your talk on Z at ${MEETUP} and think something similar/the same talk would be brilliant at our conference.

Not “our conference needs more women/people of colour/LGBT speakers”. I am already going to imagine that’s the only reason you asked me. It would be nice to know that it’s my work you’re interested in.

A shout out to Andy Allan, who organised Scotch on the Rocks. A slightly different scenario as he invited me to speak rather than asking me to submit, but it was a flawless handling:

If you are trying to encourage people new to speaking, these resources might help.

In summary

Seek out women and other under-represented groups who do great work in our field. They will not be hard to find. Pick out some examples of their work that show they’d be good for your conference. Contact them and ask them to submit. Be prepared to put some work into encouraging people.

This does take a bit more time and effort than just tweeting your CFP and leaving it at that. But if you want to put on a great conference – and why else are you bothering? – it is worth putting the effort in to seek out the people who have something interesting, new and exciting to say.

Build Quality In

03 September 2014

I am a published author! I have written a chapter on DevOps at GDS for the book Build Quality In. 70% of the royalties go to Code Club so do think about buying the book. There's a Q & A with me here.

Some thoughts on preparing an Ignite talk

07 July 2014

I did my first Ignite talk in November last year, based on roof bug-fixing, and these are some of the things I found useful while preparing.

Launch right in

I always start talks with some kind of anecdote or fact to get the audience interested, rather than a bio. Why should we care who you are until we know whether you’re worth listening to? So usually I introduce myself around the 2nd or 3rd slide.

But Russell Davies, who was incredibly helpful when I was preparing the talk, suggested I go one further – just keep telling the story. When he pitched it to me he said “it would be a brave move…”, which I took as a challenge I had to accept.

You will lose the beginning and the end

Scott Berkun’s Ignite talk on giving Ignite talks is very worth watching if you are considering giving an Ignite talk.

The main practical thing I took from it was that you will probably lose most of your first and last slide. Every time I practiced a run-through, I waited at least a few seconds before starting the first slide.

It was a good job I did. On the night, they had been playing music as people ascended the stage, but for some reason, they started mine when I was already on the stage, when I was about to start speaking. But because I’d practiced not starting immediately, it didn’t throw me, and it didn’t put me behind from the beginning.

Don’t be too tied to your slides

More great advice from Russell: don’t be too tied to your slides. Just talk, and if they coincide then it looks like you’re a genius, and if they don’t it doesn’t matter.

Do real practice

Another incredibly useful piece of advice I got from Jason Grigsby’s post about his Ignite talk was to do real practice. This is really important. When you make a mistake in a practice, then carry on – practice recovering. You will learn how to improvise until you get back on track – which is one of the most important skills for a successful Ignite talk.

They want you to succeed

People are at Ignite talks to have fun. It’s a great crowd, like doing a Best Man’s speech (yes, I’ve done one of those too) – the audience want you to do well. That, or fall off the stage.

It’s an excellent constraint

The format of Ignite talks is a good constraint to encourage creativity and I really recommend you give it a go. I enjoyed it a lot.

When it was finished I’d made quite a few mistakes and missed out things I’d wanted to say, but on balance, I think it went pretty well. Judge for yourself.

Using Git to refactor vCloud Tools into separate gems

04 June 2014

When I started working on vCloud Tools, we had most of our functionality in one repository. There wasn’t a clear separation of concerns – the code was tightly coupled – and it also meant that a user who only wanted to use one tool to do one job had to install the whole thing. So I pulled out each functional area into an individual Ruby gem.

Rewriting history

When creating the repository for each new gem, I didn't want to lose all the commit history; it is very useful documentation. If I had started each gem from scratch, the commit history would remain in the vcloud-tools repository, but I prefer not to have to go somewhere else to see the history of what I'm working on right now.

I also didn't want to create each directory side-by-side and then delete the unnecessary code, as this would make each repository much larger than it needed to be (as Git stores all the history) and would essentially be several duplicated projects with different bits deleted.

What I really wanted was to go back in time and to have started with this structure from the beginning.

Luckily, Git provides a mechanism to do this: git filter-branch.

Creating the new repository

To get started, I cloned the existing vcloud-tools repository locally:

git clone --no-hardlinks /path/to/vcloud-tools-repo newrepo

You need the --no-hardlinks flag because when cloning from a repo on a local machine, files under .git/objects/ are linked to the original to save space, but I wanted my new repo to be an independent copy.

I then deleted the remote in newrepo. I didn't want to push my new, pared-down repo over vcloud-tools.

git remote rm origin

Deleting irrelevant code

Having made a new repository, I then pruned away any code that was unrelated to that tool. So for example when pulling out vCloud Core, I pruned away all directories that didn't contain vCloud Core code.

For this, I used a tree-filter. This checks out each commit and runs a shell command against it, in this case rm -rf c, where c is an irrelevant directory or file.

git filter-branch --tree-filter "rm -rf c" --prune-empty HEAD

Because it's checking out each commit, it takes some time to do it this way (though it speeds up, as using --prune-empty removes commits that are left blank after the shell command does its job, so the total number of commits decreases as you progress through the task).

This command actually allows you to use any shell command you want, but I found that deleting things I didn't require one-by-one, while time-consuming, meant that I picked up some things that had been missed, for example files in the wrong place and tidy-up that needed to be done.

Tidying up

After each time you run this command and prune away files or directories, you need to do some cleanup. (I just wrote a little shell script and ran it each time.)

When you run git filter-branch a .git/refs/original directory is created, to allow for a restore. These objects will be retained if you don't remove them so you need to remove the references:

git for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git update-ref -d

These are usually cleaned up by Git on a scheduled basis, but because I was going on to remove other folders, I wanted to expire them immediately, and then reset to HEAD in case that had changed anything.

git reflog expire --expire=now --all git reset --hard

Then, I forced garbage collection of all orphaned entities.

git gc --aggressive --prune=now

The final line of my shell script just output the size of the .git folder so I could see it getting smaller as I pruned away unneeded code.

du -sh .git

Important warning!

You need to be extremely careful when rewriting history. It is very important not to do this on a public repository unless you have a very good reason, as it makes everyone else’s copy of that repository incorrect. So I waited until it was finished and I was happy with my local version before pushing it up to a new repository.

Applying gem structure

For all tools other than vCloud Core, the first thing I had to do was redo the directory structure.

I also had to move the file that loads the dependencies, and during the pruning process is became clear that we had a lot of dependencies at the wrong level, or not required at all. Deleting code is very satisfying!

I then added the required files for a gem, for example a gemspec, a licence. At this point, I also added a CHANGELOG to help us move the tools to open source.

Some interesting things about Git

I discovered some new things. For example, Git is case-insensitive with regard to file names.

git mv spec/vcloud/fog/Service_interface_spec.rb spec/vcloud/fog/service_interface_spec.rb

told me:

fatal: destination exists, source=spec/vcloud/fog/Service_interface_spec.rb, destination=spec/vcloud/fog/service_interface_spec.rb

You need to force it with the -f flag.

Also, you can copy commits from another repository, as if you were using git cherry-pick to copy from a branch in the same repository, by creating a patch and applying it locally.

git --git-dir=../some_other_repo/.git \ format-patch -k -1 --stdout | \ git am -3 -k

Then I published the gem

To enable our continuous integration, I added a Jenkins job and a Jenkins hook to GitHub so that a commit to master will trigger a build in Jenkins.

Once I was happy that everything was present and correct and it was ready to publish, I added a gem_publisher rake task, and then included that in Jenkins. This means that when a commit is merged to master, if the tests pass and the version has changed, the new version is automatically published to RubyGems.

Ta-dah! vCloud Core.

Finally, I made a pull request on vCloud Tools to remove it.

Pulling out all gems

Over a couple of months I pulled out all the gems and the architecture of vCloud Tools now looks like this:

hand-drawn diagram of vCloud Tools
architecture

This approach follows the UNIX philosophy of simple tools that do one thing, which together can form a toolchain to do do more complex tasks. vCloud Core now takes care of the interactions with fog and the vCloud API, and the other tools depend on that. vCloud Tools is now a meta-gem that pulls in all the other gems as dependencies. This has definitely made it easier to develop on and use vCloud Tools, and I learned a lot about Git and Ruby gems along the way!

This post originally appeared on the GDS Technology Blog.

Sketchnoting

17 May 2014

At Scottish Ruby Conference earlier this week, among the many great talks I attended was Jess Eldredge’s excellent introduction to sketchnoting.

I liked the idea of doing sketchnotes since I came across the first ones I saw, by Amanda Wright, but had never properly tried it. I do makes notes in a fairly visual way – here, for example, are my notes from Kerri Miller’s excellent talk on concurrency.

concurrency notes

The main thing of course is that my handwriting is atrocious.

I was right at the front in Jess’s talk and felt self-conscious, so the notes I made were actually worse than my usual standard.

original sketchnotes notes

However, I was inspired, and also happened to have a nice pen with me, so tried to do a sketchnote in my last talk of the day, André Arko’s very interesting Development was the easy part.

tip of the iceberg notes

Not amazing. But better than my usual notes.

What I like

Jess’s advice was very practical and could be immediately applied. For example, the title is the bit that looks really good, and that’s because I got there early as she suggested and wrote it before the beginning of the talk.

Her main advice for bad handwriting was to slow down – and I did, and it really helped, in that I can actually read this, unlike my usual scrawl.

I did find it made me concentrate a bit more as everything André said I was trying to figure out what the key point would be to that section so I could write that down.

What I didn’t like

However, I clearly ran out of space. Data stores in the bottom right (above request time) was the last section he covered. The bit I missed out was that redis-sentinel runs an election and while it’s running, all candidates accept writes, but then when one is elected, all the unelected ones throw away their writes.

It’s a shame that this is the one thing I was unable to write clearly, as that was the only thing he said that was completely new to me. That made me realise that I was worrying too much about how the notes would look to other people and whether they’d be able to follow them, so writing things down that I already knew. Whereas one point Jess made several times was these are my notes, and don’t need to make sense to anyone else.

Also, a lot of things I note down in talks are actually items for my To Do list, either unrelated if my attention is wandering or, if I’m engaged, how I can apply these things in my projects. I probably don’t want to capture all of that for posterity.

So what did I learn?

It’s worth taking a nice pen and some plain paper to a conference, because at least I can make notes that will be easier for me to read when I’m looking back at them. I might even buy an artist’s pen, as I really like the shading Jess did.

If I slow down, my handwriting is almost legible!

It’s fun. I always fancied doing the bits of comic-book drawing that didn’t require artistic talent, like cross-hatching – this is my chance!

Another go

I decided to write up the notes from Jess’s talk again:

better sketchnotes notes

Better!

Building tools to provision our machines

07 May 2014

Over the last few months, I’ve been leading a small team building tools to automate creation and configuration of our servers.

Tools to automate provisioning

Currently, our production environment is hosted with Skyscape, and we manage it using VMware vCloud Director. Skyscape, and other providers using vCloud Director, expose a UI for managing VMs and networks.

However, a UI isn't suitable when you need to bring a lot of machines up in a repeatable, reliable way, for example when migrating the site to a new platform. In addition, if you can automate provisioning, the configuration files represent your infrastructure as code, providing documentation about your system.

VMware vCloud Director supports the vCloud API, but there was no widely-available tooling to orchestrate this kind of operation using the API. So we built vCloud Tools.

Our suppliers currently all use vCloud Director

The UK Government’s policy is cloud first and we procure services through CloudStore (which uses the G-Cloud framework). As government, it’s vital that we provide secure, resilient services that citizens can trust, and we need various assurances from our suppliers to support that.

There are a number of Infrastructure as a Service (IaaS) platforms that are able to provide these assurances, but when we procured our current suppliers last year, the vendors that met our requirements (both technical and non-functional, eg self-service provisioning, a pay-as-you go cost model) used vCloud Director.

We very much want to encourage potential new suppliers, but given the availability in the market, we can be reasonably certain we’ll be using at least one VMware-based solution for at least the next 12-18 months, and it’s likely that many other transformation projects will also be drawing on the same pool of hosting providers. So it’s definitely worth investing time to make provisioning easy.

Preventing vendor lock-in

Having an easy way to provision environments will allow us to move more easily between vendors that use vCloud Director, which will help prevent supplier lock-in. But we also don’t want to lock ourselves in to VMware, so we are taking several steps to guard against that:

Previous iterations of provisioning tooling

Automation of provisioning is something we’ve been iterating on since we launched GOV.UK 18 months ago. Prior to vCloud Tools, we used a tool we had built called vCloud Provisioner. This was really useful when moving onto our first platform, but because it was built quickly it has a lot of hard-coded detail about the environment, so it doesn’t help us be flexible when moving between suppliers. In addition these hard-coded details include sensitive information, so we can’t share it, meaning it cannot be useful to anyone outside of the GOV.UK team.

Several members of the infrastructure team worked on subsequent iterations of the provisioning tooling. These iterations included vCloud Box Spinner and vcloudtools. However, the people working on these were building these tools alongside their other business-as-usual work keeping GOV.UK up and running, so when they ran into issues, it was difficult to find time to address them. With the migration to the new platform looming, we needed to prioritise this piece of work in order to be able to bring up a new environment quickly, reliably and easily.

We think vCloud Tools will be more robust

There are several things we have done to improve the chances of producing robust, more widely useful tools in this iteration.

We have committed the time and resources to this, forming a small team who focus entirely on vCloud Tools rather than firefighting or other operations work, and we are coding in the open, so we won’t fall into the trap of including sensitive information that it is later too hard to factor out.

Not only are the GOV.UK team “eating our own dogfood” by using vCloud Tools to provision our new hosting environments, there are two other GDS teams also using the tools, the Identity Assurance Programme and the Performance Platform. Other exemplar projects have started using the tools, and we have already accepted pull requests from people we do not know, so there is the beginnings of a community around the tools. This keeps us from making it too GOV.UK specific and means that we get a lot of extremely useful user feedback.

And in the meantime we are contributing back to Open Source - in one recent release of fog, a huge number of the contributions were from the GOV.UK vCloud Tools team (who were, at that time, me (Anna Shipman), Sneha Somwanshi, Mike Pountney and Dan Abel).

These factors mean that we feel confident that we are going to produce tools that will continue to be very useful to us and other teams for some time.

More will follow

There will be future posts about particular aspects of what we’ve done and how, including one soon on how we used vCloud Tools in our platform migration. If there’s anything you’d particularly like more detail on, please let us know in the comments below.

This post originally appeared on the GDS Technology Blog.

Running OSS projects

03 April 2014

At ScaleSummit last week, I proposed a session on running Open Source projects. I am hoping to move the project I’m working on, vCloud Tools, from being coded in the open to being Open Source and wanted to get the benefit of the accumulated wisdom. It was an excellent session and I really got a lot out of it.

The executive summary is that if you are trying to build a community, you need to optimise for bringing people into the community, and a lot of the discussion focused around that. Here are some of the main things that I took away from it.

Good documentation is crucial

Optimise documentation for bringing people into your community. It’s unlikely to already be good for that, as you are so familiar with the code and the project that you don’t realise what someone new to it doesn’t know.

One way to do this is to make it clear that you are happy to answer people’s questions – even hundreds of questions – as long as they follow up by submitting a patch to clarify the documentation. Encourage people to raise bugs against the documentation.

Make it easy to get involved

Make it clear how people can contact you for clarification or with ideas. An IRC channel is a great, if you can make it work, but you need to be aware of certain drawbacks. For example, people tend to expect a quicker response than by email, so you need to make sure people are in it. It will be very quiet at night in the UK.

In a later discussion back at GDS we decided not to do that for this project because there would be a lot of effort to make it work and it would be an added distraction. We definitely don’t want to say “Come to our vCloud Tools IRC channel” if there’s no-one there.

As well as (or instead of) an IRC channel, you should have a mailing list. You can either make it open or make it so that only a subset of people can reply. Someone advised that it wasn’t a good idea to have lots of mailing lists, (*announce*, *discussion* etc). It was also pointed out that even if you’re not writing code, managing the community can easily become a full-time job.

The Perl community does communication well, and the example of Catalyst was given – this project has 450 committers and the maintainer has changed 5+ times. Also mentioned was this blog post about communication with newcomers to the project: Love your idiots.

Respond quickly to external contributions

One of the things that I especially wanted to know about was how quickly you should aim to respond to pull requests. This is particularly an issue in that we are going to be managing this in work time and there will be competing priorities. The general consensus was you need to respond within 24 hours, and it’s acceptable for this not to include weekends if you are clear in your documentation that this is the case. It’s important to note that the response doesn’t have to be a review or a merge, it can be as simple as a note saying “Thanks for this, I am going to review it in a couple of days”.

The most important PRs to pay attention to are the ones from new contributors. Again, optimise for bringing people into your community.

It’s a good idea to have CI run tests on PRs so you can see failures before merging – Travis is good for this as it integrates well with GitHub. However, it was stressed that it is important to review the contribution as well, even if it passes all the tests!

Communicate your vision

Something else I was particularly interested in is what do you do if you feel a well-meaning PR is pulling the project in the wrong direction? It was suggested that a lot of this comes back to documenting your original vision and being very explicit about what this software is aiming to do.

You need one person or a group of people to be responsible for maintenance, and they are the ones responsible for the vision. Someone gave the example of Mozilla in the early days who just accepted everything, and eventually had to rewrite the core offering.

But also, take it as it comes. If you as the maintainer don’t think a direction is correct, it’s completely fine for someone to fork the software, and you may later find that the fork is doing the job better. The example of GCC was given, where a separate fork existed for about 5 years, and the GCC maintainers eventually realised that the fork was what everyone was using and merged it back in.

Modularity also makes the process easier – having a common core that everyone can agree on is relatively easy, and divergence can be supported with plugins.

It is very important that if you close a PR, you do so with a clear explanation, whether this is due to poor quality or incompatible direction.

Don’t be too hardline

One thing we talked about was not being too strict with external contributors. Sometimes people might not have the experience to know how to write tests, either in general or in your particular test framework, so insisting that a PR must have tests before it can be merged is going to put people off who could have really valuable contributions. Some people said they are very happy to write tests for newbies. Talk to the contributor to find out why they wanted to make those changes and then show them the tests you’ve written, maybe asking them whether it looks like the test cases cover the functionality they wanted to add.

However, changes in functionality should definitely include updated documentation and it is more reasonable to reject a PR for lack of that.

Assume people have the best intentions

This is great advice for life in general. Even if what they are suggesting looks completely wrong and it’s hard to understand how they could have thought it was the right approach, assume they have the best intentions and proceed accordingly.

Issue tracking

We currently manage work on the project internally using PivotalTracker. My plan was, once we’re ready to make it OSS, we move remaining features and bugs to GitHub issues, and work from that. This was seen as a good idea – it makes it clear to people what we are planning to work on and (ideally!) prevents them from raising issues we already know about. It also has a major benefit – you can Google for the issue.

It must be an active project

You need to be using the software yourself, otherwise it’s a recipe for abandonware. And it’s good to make this activity clear – related to the above point about issue tracking, if all your activity is on your internal tracker and mailing list and private IRC channel, then it won’t be clear to potential users and contributors that the project is still active.

Contributing Guidelines

It is important to have contributing guidelines. This wasn’t discussed extensively in the session, but in an extremely helpful follow-up email from Tom Doran he pointed me at a number of great resources which included the Catalyst development guidelines. I also heard from George Brocklehurst who pointed me at the contributing guidelines for gitsh and also a really useful page that thoughtbot have on code review.

Something that was raised as we finished up the session and were leaving was that, especially as Government, we need to be very careful about who owns the code. For example, some people may be working for companies where their contract states that the company owns all OSS contributions.

What next for vCloud Tools?

These considerations and some others mean it will be a little while before we move vCloud Tools from coding in the open to OSS, but it was really useful to have this input which covered a lot of things I hadn’t thought about.

Many other things were discussed, including when you need a standalone website, and what tools are good for versioning documentation, but these were the things I found most useful and relevant. Thanks a lot to everyone who took part in the session, it was very valuable and constructive.

Notes

Note that ScaleSummit operates under the Chatham House Rule so none of the comments made in the session have been attributed, and thanks to Matt Bostock and Phil Potter whose write-ups (Matt’s, Phil’s), were a very useful addition to my own notes.

Are you thinking of speaking at a conference?

09 March 2014

As co-Programme Chair for SPA conference I often find myself trying to persuade inexperienced or completely new speakers that it is worth doing and that they have something great to say. Here are some of the resources that I send on to them.

Nicely expressed post – you don't have to wait to be an expert in something before you submit a talk: You can speak at a conference too.

More detail as to why what you have to say is worth hearing, and how to get started. So Why Should I Speak Publicly?

The list of accepted talks from last year's PyCon US is a long list of great-looking talks on a variety of subjects to spark ideas of what you might speak about.

If you are nervous about public speaking, this post could really change the way you think about it: Presentation Skills Considered Harmful. You are just the UI.

Finally, this is a really useful resource Mairead O'Connor sent me last week, containing short posts on all aspects of talk preparation: speaking.io.

Applying for a job at GDS

24 December 2013

Over the next few months we will be recruiting for a number of roles, including developers and web operations engineers. Since a civil service application is a bit different to other jobs you might be applying for, we thought it was worth explaining what the process involves, with some detailed guidance on how to write the most unusual part of the application - a statement of suitability.

Open and fair process

There are a number of measures in place to make it more likely that applications to join the civil service are treated fairly and on their own merit. You can read more about the civil service recruitment and selection guidance on the Civil Service website, but the main thing you should be aware of is that we try and ensure objectivity by having consistent criteria that we assess applications on.

Consistent criteria

The job advert will list some essential specialist skills and competencies. The specialist skills are likely to be what you are familiar with in job applications, for example for a WebOp, “Experience configuring and managing Linux servers”.

The competencies are a bit more unusual. They reflect important civil service behaviours, like leadership and delivering value for money, because we are recruiting not just technical people, but people to become civil servants. This helps us build a team of people who are not just great technically, but also have other crucial skills, like communication and team-working.
For more information on civil service competencies you can look at this document.

Why this matters to applicants

One of the three documents we ask for in your application is a statement of suitability, which is extremely important, as it is where you get a chance to show the panel the evidence for how you meet the essential skills and competencies described in the job advert.

If a candidate's application does not show evidence of even just one of the competencies, we are not allowed to invite that candidate for interview. This may seem a little harsh, but it's actually this kind of rule that tries to ensure the process is open and fair.

Based on this, we can see how the statement of suitability is so important in the application. Your CV is unlikely to provide quite the right sort of information on its own, as CVs tend to be a collection of achievements and responsibilities. The Statement of Suitability is your opportunity to fill out the gaps in your CV and explain you have the experience to do a great job at GDS. You must remember to give examples, as that is what we are looking for in the application.

How to write a good statement of suitability

The main thing required in the statement of suitability is that you demonstrate the essential skills and competencies asked for. Here is an example.

We recently advertised for Web Operations Engineers (and will be doing so again - watch this space!). One of the essential competencies we are looking for is evidence of how you "coach and support colleagues to take responsibility for their own development (through giving accountability, varied assignments and on-going feedback)".

If you have managed a team, it should be fairly straightforward to think of an example. But if you haven't, there are other ways you can provide this evidence.

The point here is that we feel an ability to coach and support colleagues is essential to being successful in the role, and we are looking for evidence that you have done this in some context before.

A word on how to phrase your answers

It's good to give detail, but your answers don't have to be really long. The best thing to do is think of the example you want to use and give us the essential information.
It may be useful to think of the CAR approach:

If you've covered all these points, you will have structured your example to give us all the information we need.

How to structure the statement

You might find it helpful to list each of the essential skills and competencies as headings and give an example under each, or you may prefer to write it in a letter or essay format. The structure is not important - just make sure that you cover all of the essential competencies asked for.

The other documents

The other documents we require are your CV and CV cover sheet. There's nothing different about how you should structure your CV compared to applying for a job in the private sector.
The CV cover sheet is a form which requires you to fill in some straightforward details so that we know how to contact you. Download this from the very bottom of the job application page, and include it with your application. If you are not already a civil servant you only need to complete three parts of this form. For existing civil servants, you need to fill in more sections of the CV cover sheet - your line manager should be able to help you with this.

Interview stage

Once we have sifted all of the applications we invite some of the applicants to interview. All candidates are asked a consistent set of questions for that role, and you are likely to also have to do some kind of coding or whiteboard exercise. If you are called for interview, you will get more information about what to expect in advance.

This post originally appeared on the GDS Technology Blog.

How Anonymous Submissions Affected Gender Balance at our Conference

17 November 2013

Mainly inspired by this article, I proposed that we make submissions anonymous for SPA2013. The committee (four of us) discussed what we thought the outcome would be for some time, before deciding to just try it and see how it worked out. And here's the answer.

The conference

Firstly, a bit about SPA. It stands for Software Practice Advancement, and it's a very interactive conference – you are unlikely to be sitting in a talk. You'll be writing code in a new language, or doing a group exercise in a process track, or taking part in a goldfish bowl discussion, or actively learning in another way. It's a great conference, and if you're interested in checking it out we are holding a free one day taster with some of the best sessions from this year in Cambridge on 23rd November. MiniSPA. It's free!

Enough pitching. I've attended SPA three years running and became co-Programme Chair for the 2013 conference, and while I think it's very good, one thing I think would improve it is more women leading sessions. I would also like it if we could get a greater diversity of speakers in other ways, but I thought I would focus on women for starters.

Stats

The first year I attended, SPA2011, there were 28 sessions, with a total of 43 session leaders between them. Of those 43 session leaders, 38 were men and the remaining 5 were women.

Other interesting things I noticed were that four people presented more than one session at the conference – all four were men. Only nine sessions were led by just one person, and of those nine, eight were men.

2011

5/43 = 12% of the session leaders were women.

1/9 = 11% of the solo session leaders were women.

0/4 = No women ran more than one session.

The next year, there were 30 sessions and 42 presenters. Four were women. Again, the five presenters running more than one session were all men. Ten sessions were led by a single presenter – 8 men and 2 women (one was me!).

2012

4/42 = 10% of the session leaders were women.

2/10 = 20% of the solo session leaders were women.

0/5 = No women ran more than one session.

How we did anonymity

At SPA we have three stages after submission of proposals.

  1. A feedback stage, where people offer advice to help the session submitter improve the submission (which can be edited up until the deadline).
  2. A review stage where at least three reviewers grade a submission according to whether they think it should be included in the programme.
  3. A programme meeting, when we pull the reviews together and decide on the programme.

In previous years, the presenters' names appeared alongside their submissions all the way through. This year, we made them anonymous right up until we had put together a draft programme, and then we did the big reveal, just to check that we hadn't scheduled one person to do several sessions at the same time, for example.

Results

So did it make a difference?

At SPA2013, we had 27 sessions with 46 presenters, 40 men and 6 women. Of those, two were repeat session leaders (both men) and 10 sessions had single leaders, of whom one was a woman.

2013

6/46 = 13% of the session leaders were women.

1/10 = 10% of the solo session leaders were women.

0/2 = No women ran more than one session.

So no, not really.

That is – to the number of women speaking. A lot of the conference feedback praised the variety of sessions and topics, more so than in previous years. So we did something right. I also don't know whether it made any difference to the number of women who submitted, as I don't have that data.

But there were two other very interesting outcomes.

Lack of positive bias is good for everyone else

The first unintended – but good! – outcome was that people new to speaking at the conference felt much more able to submit.

A very representative comment from the survey I conducted was:

"Since I haven't spoken at SPA before, I expect being anonymous helped me compete with regulars."

And correspondingly, the reviewers had a lot of very similar comments. Here's one that sums up most of them:

"We used to have too many reviews along the lines of 'a bit weak but I know Alice and Bob and they'll do a good job'. They didn't always do a good job and it resulted in too many repeat speakers, which I think new potential speakers find off-putting."

Many of the reviewers admitted they didn't actually like anonymity but realised it helped prevent bias. Of course, we are generally not aware of our subconscious biases *against* people, but one thing that anonymity made reviewers aware of was our tendency to be biased *towards* people we know. But of course, that kind of positive bias means that someone merely unknown will have to work harder to get their session considered.

Positive discrimination can be off-putting

The second benefit of the anonymity became apparent in a scenario that I hadn't even considered. One submitter proposed a session about probabilistic data structures, which looked excellent, but her language of choice was Haskell, and most of the feedback focused on attempting to get her to change to a more widely used language. Based on that, she concluded that the talk probably wasn't right for SPA, and assumed that she would later hear it had been rejected.

In fact the talk was very popular with the reviewers, receiving top grades from all of them, so it was a shoe-in for the conference. But when we contacted her to let her know she was in the programme, she initially said she was no longer able to give the talk. A day or so later, she got back in touch to say – to our relief – that she actually was available, and explained her initial reluctance:

"Truth is the session feedback concluded that the idea wasn't right for the conference, so I inferred that you must've accepted the session because I'm female, and had a bit of an emotional reaction; like any human I want to have opportunities based on my own merits."

In actual fact, this was not what had happened, as neither I nor any of the reviewers knew who she was. Her session had been accepted purely on the merits of the submission. And a massive advantage of the anonymity we had put in place meant that we could claim with certainty and evidence that we were not making decisions in a biased way, either for or against her submission based on her gender.

A possible objection

Some people surveyed felt that it might be appropriate to remove the anonymity at the review stage. Ability to present content can be at least as important as the content itself, and people felt the best way to get this information was from knowing who the speaker is. Here is a representative comment:

"I think that the knowledge of a presenter's past delivery can be a big differentiator when you get submissions of similar quality."

But really, this is just another way of saying we want to know when people are well-known – we want to put Alice and Bob in because they always do a good session.

Yes, a speaker's delivery and structure makes a huge difference to how well a session works. However, at SPA we assign shepherds to first-time presenters (or anyone who wants one) and they can be very helpful – my excellent shepherd Adam Iley, among other things, arranged a run-through at his workplace to allow me to practice my session with an unfamiliar audience.

So if we do accept a promising session where we don't know that the speaker is good, we might be able to help with that; and conversely, I tend to think that a good presenter should be able to write a good submission so that will shine through.

Next!

In any case, the committee felt that on balance it was positive, so we are continuing with anonymity throughout the whole process this year.

Why not get involved? Submit a session, or get involved in giving feedback on sessions, or both!

Check out the call for proposals, and have a look at the previous programmes I've linked to above for an idea of the kinds of sessions we like.

And if you have any questions, or want to get involved in giving feedback, please do get in touch.

Creating a Puppet module

09 September 2013

I learnt three very interesting things recently, courtesy of the brilliant Dan Carley.

  1. git filter-branch
  2. how to create a puppet module using our puppet module skeleton
  3. shopt -s dotglob

While creating the Puppet manifests for the GOV.UK mirror, we realised we needed a module that was part of the GOV.UK Puppet, so our task was to pull it out into a standalone module and have both GOV.UK and our new GOV.UK mirror use it.

The first step in creating a new module is to pull it out into its own git repository.

First, clone the repository the module is currently in. (Extra learning here: you don't need to clone it from GitHub, you can just git clone the existing repository.) You want --no-hardlinks so it's entirely separate:

git clone --no-hardlinks puppet puppet-auditd

At this stage our puppet-auditd repo still points at our puppet repo, so we want to remove the remote:

git remote rm origin

Now we want to get rid of everything that's not our module and make our module the root, and this is where we use git filter-branch (update 2014-04-12: GitHub have removed this without a redirect – tsk! – but you can find a historical copy here):

git filter-branch --subdirectory-filter modules/audit-d HEAD

The next thing we want to do is create the files in the framework around the subdirectory to make it a Puppet module, for example the Modulefile. For this we can use our Puppet module skeleton. However, we don't want to directly follow the instructions there as we already have a lot of the classes we need. Instead of creating it from scratch as per those instructions, we generate our new module stucture:

puppet module generate gdsoperations-auditd

and then then we copy over the generated files.

However, a normal recursive copy won't work:

cp -r A/* B

This will only copy non-dotfiles, and we want the dotfiles as well, like .gitignore.

However, attempting to copy the dotfiles as well:

cp -r A/.* B

leads to hilarious results. .. is a directory too, so the above command copies all those contents recursively as well. Try it. It's most entertaining. But it's not really what we want.

What we can do is toggle what is included in A/* for this shell. The documentation is here, but this is what we need:

shopt -s dotglob

In order to check what is going to be copied now you can:

echo A/*

and if you like it:

cp -r A/* B

The next step is to go through the files to work out which modifications to keep and which ones are not relevant.

Another tip from Dan: vimdiff is really useful for this task. I won't go into how and what we decided; you can see that here.

Some Regex in the form of a Picture!

10 August 2013

Where Do I Start?

06 July 2013

The first day at a new job is always a bit nerve-wracking. In a recent session at SPA 2013, we came up with some things a developer joining a new team can do to get up to speed quickly.

Whiteboard an architecture diagram

This is a brilliant way to get a quick overview of how the pieces of your new project fit together, and can be tailored to whatever level of understanding you (or the person you are talking to) has. It's a good way to meet people on other teams, when you're looking to get more detail on some of the parts of the diagram. And your fresh perspective can often be very useful to the person taking you through the architecture.

However, it can sometimes be hard to know who the right person is to ask, and it can also be hard to get the right level of detail.

Facilitate a retrospective

This is the fastest way to find out what's going on in a team, and beacuse you're new, you will essentially be an external facilitator which is really useful to the team. It's also a great way to find out what's going on in other teams once you've settled in.

However, it could be challenging if your new place of work is not used to agile working, and of course you do have to be the kind of person who has the confidence to faciliate a retrospective for a bunch of people you don't know yet.

Start putting a glossary together

...with the aim of putting it on the wiki.

This will give you a head start on understanding the concepts that the rest of team take for granted – and has the added advantage that you may hit on areas of vagueness or disagreement that can be straightened out.

It can however be hard to get started with this, and to work out what to focus on, and in some teams it might be a challenge to find anyone who understands them all.

In Summary: Do something, document something

People have different ways of learning and sometimes the explanations you get in your first week can lead to information overload and be hard to take in. So it can be useful to ask more directed questions, for example in pursuit of added detail for an architecture diagram, or to draw out actions for a retrospective.

We had some other ideas as well:

  • Pair program as much as you can, with different people
  • You could think about shadowing someone for a morning or a day
  • Talk to other teams - the teams that particularly can give you insight into what you need to know are the testing team, the support team and the ops team
  • Find out where people go for lunch and wangle yourself an invitation!
  • We also stole some ideas from other teams, like if the team's processes are not documented you could offer to do that as a way to gain understanding. For example, how well documented are the new joiner instructions? You are in a great place to improve those, and a big win would be automating some part of that. Also, meeting the users is a fantastic way to understand the business, so if that's not part of your induction you could arrange that.

    Thanks to Andy Longshaw, Eoin Woods and Nick Rozanski for organising the session.

    Roof Bug-fixing

    21 May 2013

    I often find myself viewing life through the lens of software development, a bit like when you play too much Tetris and all your friends turn into shapes. But recent events have made me think: maybe other things actually would be better if they were more like software development?

    Recently, I had a leak into my flat. By "recently" I mean it's been ongoing for four and a half months, but that's not what this post is about. This is about applying software development ideas to other fields, instead of the other way around. We talk about "software craftsmanship" – I'm thinking about the opposite, as applied to, for example, roofing.

    I first noticed the leak as I was about to go on holiday before Christmas. It rained very heavily, and literally hours before I was due to leave, I saw water bubbling up between the laminate floorboards in the hall. I pulled up the vinyl on the bathroom floor and then took the side of the bath off, and found that my bathroom was about an inch deep in water.

    Cut forward a fortnight to when the housing association manage to send out a surveyor to investigate. He tells me what is causing the problem: the flat above and to the right has – without permission – erected some kind of structure on their balcony, and this has caused damage to the brickwork, so when it rains water is seeping into my flat through the holes in their balcony.

    At this stage, it's a bit of a mystery to me how that works. And why shouldn't it be? I'm not a roofer. Or a surveyor, or a builder, or an architect. I have only the vaguest notion of how buildings are put together, and I don't think to ask for an explanation of how the water is filling up my flat. Apparently, the Offending Neighbour has drilled a hole to put up the mystery structure, and the hole is the problem. They are going to asphalt over it. And they do so.

    All well and good, and the insurance company come round to measure up the flat to fix the damage. Except the day they come to do this, it rains heavily, and once again, I see water bubbling up through the floor in the hall. They have asphalted over the hole in the balcony, but this hasn't fixed the leak!

    A builder comes to my flat to discuss it with me. This is where it starts to get interesting. The builder has already looked at the Offending Neighbour's balcony and now he wants to look at my flat. But he can't see how the pieces fit together. Eventually, I have to take him outside to point at the balcony to demonstrate that water coming from the balcony at the point at which it intersects with my flat would lead to damp at exactly the spot we see it, as per the diagram above.

    This is when I first start to think of this in terms of a bug. Here is the point at which you need to look at the bigger picture. We're not talking about a bit of mistaken logic in a Ruby program affecting the output of that program. We're talking about a timeout two layers away. The manifestation of the problem is a long way from the cause, and you really need a view of the bigger picture to be able to reason about it.

    So the builder goes away, and finally (after calls and emails and threats and complaints) the housing association get back to me and tell me that they are going to put something called flashing on the point at which the wall of my flat meets the wall of ON's balcony. This, they tell me, will definitely fix the problem.

    So this makes sense to me. At this point, I've got an idea of the bigger picture, though the details of the water seeping through the brickwork and then somehow bubbling up through the floor are somewhat hazy to me. But I do have one strong opinion at this point: I want to be sure this time that they have really fixed it. At this point, I conceive of the idea of a water test.

    You see, when we find a bug in our software, we try and recreate it. Then we know when we've fixed it. And something I was starting to notice here was that this wasn't happening. It was as if I had noticed the timeout, and made a configuration change in the general area, then marked the story as done and walked away. We don't do that, with software. And yet this situation that was making my life pretty inconvenient – three months in, my flat was covered in mould, smelt of damp and all my furniture was in one room while I waited for the leak to be be fixed – was being dealt with by people who seemed to be making general stabs in the direction of the problem, without any kind of theory or analysis.

    Of course, I didn't quite realise that – you expect people to be professionals, whatever the job is. But I was sure I wanted them to do a water test.

    But getting them to do this was pretty hard, even though it seemed completely obvious to me. What's the problem? Stand on the balcony with a hose, see if the problem is fixed! At one point, I was told it wasn't "feasible". I started to wonder if I was being too idealistic and actually a building was more like a huge legacy codebase where you may not even have access to all the libraries. Maybe I'd just have to accept a best guess instead of a rigorous approach.

    Finally, four months in, I managed to persuade them to do it. The head of repairs at the housing association came round to instruct the roofer, but even as he did this he was complaining that the water test was pointless, a waste of time, as it was due to rain today anyway and that would test it. He didn't really grasp the idea that a water test is a controlled test – it's a way to control the input so as to work out whether the output is what you'd expect were your conclusions correct. Rain – apart from being unpredictable – is not controlled. For a start, it rains all over the building at once.

    But then the roofer came round, and he was a true software developer.

    We went up to the balcony together and he explained to me what he was going to do. Firstly, he was going to hose down on the balcony, not going over the edge. This was to test the flashing.

    There is a gap between ON's fence and the wall of my flat. It seemed to me that the gap was too low and my suspicion was that rainwater was overflowing through the gap and thus soaking into my wall.

    However, the roofer explained to me that this was the design of the balcony, to prevent flooding. If it rained heavily, the water would flow along the gully and into the drain, and the gap was to prevent the balcony flooding if the rain was too heavy.

    However, secondly, he explained, he was going to hose down specifically through the gap and over the side of the wall of my flat so we could see what would happen if the balcony did flood. The reason he was doing these things separately, he told me, was so he could isolate the cause of the problem. If he did both at once, we wouldn't know what the specific problem was.

    Yes! Exactly! This is why we don't make the arbitrary configuration change and correct the logic in the Ruby program at the same time, because then how do we know? This man was speaking my language!

    The first thing took him about thirty seconds to discover. They turned the hose on the flashing, the water ran down the gully as planned and then – that was it. The drain was completely blocked. It took less than a minute for the balcony to flood and the water to start pouring through the gap and down my wall. Thus demonstrating another benefit of methodical testing – you surface things you might have assumed to be different.

    Later, when unblocking it, the roofer told me it must have taken years to get to that state. One might have thought that ON would have reported it at some point in those years. But why would she? She may not even have noticed – presumably she doesn't hang around outside when it's raining. It had not occurred to any of the previous investigators of this problem to check the drain. And while it may seem an obvious thing to have checked, one often overlooks the obvious, and that is why testing is good.

    The second thing took this software genius of a roofer a few more minutes to discover. After unblocking the drain, he hosed down the side of the my building and at this point I found that there was water coming in under the bath again. He looked closer at the building and saw, under where the balcony joined my wall, a gap.

    Having hosed the wall, he had seen that water ran into that gap and from there, the easiest escape would be into my flat, rather than back out. By attempting to recreate the problem, he identified the solution.

    So he unblocked the drain, and he filled in the hole with cement. And then, as if he had not covered himself in glory enough, he told me he was only 95% certain that this would solve the problem, whereas the previous fixes, I had been assured, were the solution. He knows a building is a legacy system. But he has the software methodology approach.

    There's more learning here as well – for example, to not assume that you won't understand a problem that isn't in your field – but the main thing I took from it was this: everything would be better if it was a bit more like software development. Craftsmen should be more like software developers.

    Upgrading to 12.04...

    06 May 2013

    I needed to write some code. Thanks to George Brocklehurst, I was no longer content to do this on my personal laptop using gedit – I required Vim.

    But I could not upgrade Vim!

    Failed to fetch http://gb.archive.ubuntu.com/ubuntu/pool/main/v/vim/vim_7.2.330-1ubuntu4_amd64.deb 404 Not Found [IP: 91.189.92.201 80]
    E: Unable to fetch some archives, maybe run apt-get update or try with --fix-missing?

    OK, maybe it was unrelated, but it was time to face the inevitable. I was on Ubuntu 10.10. I needed to upgrade. Skip to what I learned from this sorry saga.

    Great, so all I needed to do was update to next package from the Update Manager, right?

    Error during update
    A problem occurred during the update. This is usually some sort of network problem, please check your network connection and retry.
    , W:Failed to fetch http://extras.ubuntu.com/ubuntu/dists/natty/main/binary-i386/Packages.gz 404 Not Found
    , E:Some index files failed to download, they have been ignored, or old ones used instead.

    Ah. Wrong. I left it so long that it was no longer supported.

    Right, so I couldn't go to 11.04. But actually, I didn't want 11.04, I wanted 12.04. So can I not just go directly there?

    Well, no, as it turns out. Or maybe you can. I still don't know. But threads like this suggested that I couldn't go directly to 12.04 without doing a fresh install and losing my files. I didn't fancy that, so I thought I'd go the long way round.

    Since I was out of time to upgrade via the Update Manager, I needed to download the 11.04 ISO, confirming that it was, as I thought, 64-bit:

    uname -m
    x86_64

    and then save the ISO to a CD. Having not done this before, I found this useful. You want the CD to have multiple files and folders, not just the ISO as one file.

    Great. So then you stick the CD in and just follow the instructions. Like these. Fine. No problem.

    Except... problem. This bit? That hung there for HOURS. If you click the arrow you can see the command it is hanging on, but Googling that on another computer (which I had by now switched on in order to continue with my life) gave me nothing.

    I'm telling you this, even though I'm embarrassed: I killed it. It had been hanging there for hours! I couldn't take it any more!

    And funnily enough, that turned out not to have an ideal outcome... it would not boot. On the plus side, it's dual boot and Windows seemed fine, though at this stage, I was pretty sure I could "fix" that too:

    Fine, never mind, all my files etc were backed up, it's no biggie. In fact, I could just install Ubuntu 12.04 at this point? Since it appeared that I may well have lost all my files.

    Except somehow, no. The other computer I was using was Windows, and – who knew? – it wasn't so easy to get the ISO onto a CD. After some trying, I gave up.

    Next plan was to install 11.04 from the disc I actually had. And, to my joy and incredulity – THIS WORKED!

    And then, amazingly, the upgrade to 11.10, and then 12.04, could be done via the Update Manager. Finally, six hours after I'd embarked on this foolish mission I was able to report back:

    ...shortly followed by...

    So what have I learned?

    1. How to check your system is 64-bit.
    2. How to embed tweets into blog posts (click the 'More' button to the right of the 'Favourite' button and all will be revealed).
    3. Not to put off the upgrade until such time that it's no longer supported and you have to go through all this!
    4. ALWAYS be backing up your files. As Jeff Atwood said, "until you have a backup strategy of some kind, you're screwed, you just don't know it yet". This could've been much worse for me.

    Happy programming!

    Partitioning!

    24 April 2013

    Today I learned from the awesome bob how to add storage to a box, including partitioning, mounting, and other things I'd heard of but had never done myself.

    We had to add some storage to the elasticsearch boxes. We generate a lot of logs and they all go to elasticsearch. By default when we provision servers we give them 32GB but this wasn't enough. So here's how to do it:

    1. Add the extra disk through our virtualisation platform's control panel.
    2. Reboot the box so that it sees the new disk.
    3. Partition the new disk. There are many ways to partition a disk - we used cfdisk, which has a GUI.
      cfdisk /dev/sdb
      This opens the GUI and then you tab through it to select options. We just accepted all the defaults, so the only time we had to change it was at the end, to select [write]. We did consider making the type Linux LVM as this would have meant we could extend it later, but in this case we just accepted the default type of Linux.
      This means that as well as /dev/sdb we have /dev/sdb1. (Extra learning points here - disks are added alphabetically. So the existing disk was sda. If, subsequent to this, we add another disk, it will be sdc.)
    4. Before we can mount the disk we need to give it a filesystem. We gave it ext4 because "everything uses ext4 these days" (bob). If you don't have a good reason for picking one of the others, then use ext4.
      mkfs.ext4 /dev/sdb1
    5. Now we mount the new disk to a temporary directory:
      mkdir /mnt/tmp
      mount /dev/sdb1 /mnt/tmp
    6. At this point we need to stop elasticsearch and also disable puppet (otherwise it will just start elasticsearch again on its next run):
      service elasticsearch-logging stop
      puppet agent --disable
    7. Now we need to copy the elasticsearch indices to the new disk. Because the indices are just files you can rsync them, as long as elasticsearch has been stopped, which it has.
      rsync -av --stats --progress /mnt/elasticsearch/* /mnt/tmp
      The -v flag above is 'verbose', and in addition, the stats and progress options give some more noisy output while the rsync is going on. Often, when using rsync you would want to add -z, but since this is just from one disk to another and not going over the wire then there's no need here. Finally, -a is 'archive'. As the man page helpfully notes, this is "same as -rlptgoD (no -H)". I will leave that as an exercise for the reader.
      This stage takes some time.
    8. When it's finished, we did two things, just as a (slightly paranoid) check to see if it worked:
      1. Run the same command again. If it has successfully rsynched everything, the two will be the same so it will output immediately.
      2. du -sh to check that /mnt/elasticsearch and /mnt/tmp are the same size.
    9. Instead of mounting the new disk in the same way as step 5 above, we can edit /etc/fstab. We add this line:
      /dev/sdb1 /mnt/elasticsearch ext4 defaults 0 0
      We should have thought about using Puppet here, as doing it like this means there are parts of the infrastructure that are not code.
    10. Next, we unmount sdb1 from /mnt/tmp:
      umount /mnt/tmp
    11. Then, we move the old elastic search directory and create a new one:
      mv /mnt/elasticsearch /mnt/elasticsearch-old
      mkdir /mnt/elasticsearch
    12. Now mount the sdb1 to the new elasticsearch. Because of step 9 above, we can pass either the mount directory or the directory to be mounted; we do not need both. This has the added advantage of testing our fstab setup.
      mount /mnt/elasticsearch
    13. All done! Now we need to:
      1. Restart elastic search
      2. Re-enable puppet
      3. Delete /mnt/tmp and /mnt/elasticsearch-old

    Roof Hacking

    24 March 2013

    Two weeks ago I was at the excellent /dev/fort. More on that another time; all I'll say now is that we were making a website in a fort.

    On one feature I was pairing (actually, tripling...) on some Django with the awesome George Brocklehurst and the brilliant James Coglan. James and I took a break to look at the causeway being underwater at high tide, and when we returned we found that George had relocated from our previous office (the green sofa) to the flat roof of the officers' mess. With his phone playing Ben Howard's cover of Call Me Maybe and glasses of whisky hand-delivered by the fantastic Chris Govias, it was perfect.

    Except it wasn't, because George's battery was running low, and he couldn't push his changes to my laptop because the wifi didn't reach that far. "Of course, we could always set up a local wifi on the roof," said George. Was he trolling me? No, he was not, and here's how:

    George committed to a local branch and then set up his mac as a network hub (a computer-to-computer network).

    Then I added a git remote that pointed at the repository on George's machine:

    git remote add george georgebrocklehurst@169.254.145.66:code/devfort7/hobbit/.git

    The IP address here was his machine on the network he'd created, and it was his ssh login (so I needed him to enter his password).

    This included the pleasure of having to type:

    git fetch george

    Then I merged george's branch into mine:

    git merge george/onboarding

    and we were ready to use my computer to continue the good work.

    Photo by the aforementioned brilliant James Coglan.

    How to Estimate

    21 January 2013

    I want to share this great idea about estimating that came from the excellent Mazz Mosley. Instead of worrying about estimating in hours or days, estimate in story points as follows:

    1: This is trivial. I know exactly the code I would write if I went back to my desk right now.

    2: This is quite easy. I know roughly what I'd have to do. I might have to look one or two things up.

    3: This is a bit complex. I might have to refresh my memory on a few things and there are a couple of unknowns.

    5: This is big. I have only a rough idea of how I'd do this.

    8+: I don't know how to do this.

    I've written 8+ rather than the more standard 8, 13, 21 etc because in our team we had an additional rule – if it's 8+ then the story is too big and you need to break it down a bit more. Maybe have a timeboxed spike? Then you will have more information for the next planning meeting.

    It doesn't matter how much time each point ends up being (and this will vary from team to team); after a few sprints of estimating like this the velocity will become meaningful and you can use it for predicting how much work you'll get through in future sprints.

    Testing the redirections

    10 December 2012

    Now that GOV.UK has replaced Directgov and BusinessLink, and departments are moving to Inside Government, we want to make sure that people visiting links to the old sites get where they need to be. We want them to be redirected to the correct page on GOV.UK, with no link left behind.

    This post is about the tools we built to make that possible.

    The first thing we needed was a list of everything we wanted to redirect: all the Directgov and BusinessLink URLs (links and Web addresses). This proved to be a fairly significant task - both sites had long histories and various different providers, so a comprehensive list of these URLs did not exist.

    Instead, we collected our own lists from a variety of sources, including traffic logs, records of friendly URLs (shorter, more memorable links that redirect to longer URLs), and the results of spidering the sites.

    This gave us a total of about 8,000 Directgov URLs and about 40,000 BusinessLink URLs.

    Wrangling the URLs

    Many of the lists of URLs existed in various spreadsheets, maintained by different people. We needed a canonical source of truth. So we built the Migratorator.

    The Migratorator is a Rails app, backed by a MongoDB database. It allows multiple users to create one-to-one mappings for each URL, where the mapping consists of the source URL, status (whether it will be redirected or whether, no longer representing a user need, it is now gone) and, if applicable, the page to which it will be redirected.

    Migratorator image

    As well as the mapping information, the Migratorator allows us to capture other useful information such as who has edited a mapping, tags showing information about the type of mapping, and a status bar showing how far through the task we are.

    Migratorator detail

    Checking the mappings

    We needed to confirm that the mappings were actually correct. We wanted several people to check each mapping, so we created the Review-O-Matic.

    The Review-O-Matic is also a Rails app and uses the Migratorator API to display the source URL and the mapped URL in a side-by-side browser, with voting buttons.

    Review-O-Matic

    We asked everyone in GDS to help us by checking mappings when they had some spare time. However, clicking through mappings can be dull, so we ran a competition with a prominently displayed leader board. The winner, who checked over 1,000 mappings, won cake.

    Confirmation from departments

    The Review-O-Matic presents the mappings in a random order, and the way it’s set up means that links within pages cannot be clicked. This is good for getting as many mappings as possible confirmed, but our colleagues in departments needed to check content relevant to them in a more methodical and interactive way. Enter the Side-by-side Browser.

    The Side-by-side Browser displays the old and the new websites next to each other. Clicking a link on the left hand side displays what this will redirect to on the right hand side.

    Side-by-side browser image

    The Side-by-side browser is a Node.js proxy that serves itself and the site being reviewed on the same domain, so that it’s ‘live’ and not blocked by the Same-Origin policy. We joked that, in essence, the side-by-side browser was a phishing attack for the good!

    Initially it used the Migratorator API for the mappings. However, once we’d built and deployed the Redirector, we could use that instead to populate the right hand side. As well as simplifying the code, this meant we could now see what the Redirector would actually return.

    At this point, we distributed it to our colleagues in departments to check the mappings and raise any concerns before the sites were switched over.

    Bookmarklet

    We used another trick to test Directgov mappings while the site was still live. We created a domain called aka.direct.gov.uk, which was handled by the Redirector, and a bookmarklet. By replacing the ‘www’ with ‘aka’ the bookmarklet allowed us to see what an individual Directgov page would be replaced with.

    The Redirector itself

    For the actual redirection, we use the open-source Web server Nginx. The Redirector project is just the process for generating the Nginx configuration. It’s written mainly in Perl with some PHP.

    Generating the Nginx config requires logic to determine from the old URL what kind of configuration should be used.

    For example, the important part of a Directgov URL is the path, e.g. www.direct.gov.uk/en/Diol1/DoItOnline/Doitonlinemotoring/DG_196463, while for BusinessLink the essential information is contained in the query string, e.g http://www.businesslink.gov.uk/bdotg/action/detail?itemId=1096992890&type=RESOURCES. Redirecting these two types of URL requires different types of Nginx config.

    This logic, plus the mappings we gathered, make up much of the Redirector project.

    The joy of tests

    In addition, the project contains a suite of unit and integration tests, including one that runs every night at 5am. This test checks that every single URL in our source data returns a status code that is either a 410 ‘Gone’ or a 301 redirect to a 200 ‘OK’.

    For a few weeks before the launch we also ran the daily Directgov and BusinessLink logs against the Redirector to see if there were any valid URLs or behaviour we’d missed. By doing this we found that, for example, even though URLs are case-sensitive, Directgov URLs were not, and users would therefore expect www.direct.gov.uk/sorn to work in the same way as www.direct.gov.uk/SORN.

    Going live!

    The final task was to point the DNS for the sites we’re now hosting at the Redirector. Now users following previously bookmarked links or links from old printed publications will still end up on the right place on GOV.UK.

    redirector post-it gets lots of votes at retrospective

    The configuration now has over 83,000 URLs that we’ve saved from link rot, but if you find an old BusinessLink or Directgov link that’s broken then let us know.

    Traffic through the Redirector is easing off as GOV.UK pages are consistently higher in the Google search results, but it’s been really exciting making sure that we do our best not to break the strands of the Web.

    This post originally appeared on the GDS Blog.

    Learning the perls

    20 November 2012

    After some time muddling through with Perl, I have accepted the inevitable – it's time to actually knuckle down and learn it properly. I have acquired some books, but I also require some direction – so I asked my excellent colleague and friend Mark Norman Francis to write a brief guest post for my blog.

    His instructions were "Complete the sentence: In order to understand C you need to understand Pointer Arithmetic. In order to understand Perl you need to understand...". He went many better, and produced the following:

    In order to write perl in a modern context, I think these are the basic skills you'll need.
    1. Perl's provided documentation is extensive and worthwhile, so learn to use `perldoc` to read both the provided manuals and the documentation of the builtin perl functions.
    2. Learn the difference between variables – scalar, array, hash, and references (hint for references: learn to make a hash of hashes).
    3. Learn how to use an array as a stack.
    4. Basic regular expression usage – matching, replacing, capturing substrings, case-insensitivity, metacharacters, and writing more readable expressions by having perl ignore the whitespace.
    5. Learn to use perl on the command line as a pipe filter instead of awk/sed.
    6. Learn how to write your own functions.
    7. Learn how to use core modules such as `File::Find` (write a tool to list files in a directory structure from smallest to largest in size).
    8. Refactor the code from step 7 to use a Schwartzian Transform to sort the file sizes.
    9. Learn how to install third-party libraries from CPAN.
    10. Install Moose from CPAN, then work through `Moose::Manual` and `Moose::Cookbook` to learn to write modern OO perl.
    11. Learn how to use `Test::More` to test code and `Devel::Cover` to produce coverage reports.
    12. Find an abstract intro to OO example (such as employee payroll) and write it in Moose with full unit test coverage.
    13. Lastly, read the `perlstyle` documentation, and then write your own style guide.

    Thanks, Norm. Thorm.

    Learning More About D3

    19 July 2012

    I had a really inspiring chat with Matt Biddulph about D3 this week. He showed me some really cool things. I made some notes.

    CAP again – or should that be PACELC?

    15 July 2012

    The last thing I wrote about was the CAP Theorem. Last week, Tom Hall visited our office and gave a very interesting talk, the central thesis of which was that the CAP Theorem, as often explained, is incorrect – or at least not very meaningful.

    The first point, explained very clearly in CAP Confusion: Problems with 'partition tolerance' is that P, "Partition Tolerance", as per the proof of the CAP Theorem, is not a property of your application; rather it is a property of the network it's on. The network may partition. To quote from Henry Robinson's Cloudera article:

    "Partition tolerance means simply developing a coping strategy by choosing which of the other system properties to drop. This is the real lesson of the CAP theorem – if you have a network that may drop messages, then you cannot have both availability and consistency, you must choose one."

    The rest of the article is very worth reading.

    The second point Tom covered is from Problems with CAP, and Yahoo's little known NoSQL system by Daniel Abadi. Abadi covers the point above very clearly, and then points out that there is a missing letter from CAP – L, for latency.

    "Keeping replicas consistent over a wide area network requires at least one message to be sent over the WAN in the critical path to perform the write... Unfortunately, a message over a WAN significantly increases the latency of a transaction... Consequently, in order to reduce latency, replication must be performed asynchronously. This reduces consistency."

    He suggests CAP should be rewritten as PACELC:

    "If there is a partition (P) how does the system tradeoff between availability and consistency (A and C); else (E) when the system is running as normal in the absence of partitions, how does the system tradeoff between latency (L) and consistency (C)?"

    Tom's talk covered many other interesting topics and is worth catching if you can. One of the other many interesting things Tom talked about was Vector Clocks. I won't go into that here, but they are worth reading up on! Here is a potential place to start...

    The CAP Theorem and MongoDB

    29 April 2012

    This week I learned some things about MongoDB. One of them was about how it fits in with the CAP theorem.

    They say a picture is worth a thousand words, and I think this diagram from my excellent new colleague Mat Wall while he was explaining it to me says everything:

    Over and out.

    OK, perhaps I can offer a tiny bit of exposition.

    The CAP Theorem is: where C is consistency, A is availability, and P is partition tolerance, you can't have a system that has all three. (It gets to be called a theorem because it has been formally proved.)

    Roughly speaking:

    If you have a web app backed by a SQL database, most likely, it is CA.

    It is C because it's transaction-based. So when you update the database, everything stops until you've finished. So anything reading from the database will get the same data.

    It can be A, but it won't be P because SQL databases tend to run on single nodes.

    If you want your application to be P, according to the CAP theorem, you have to sacrifice either A or C.

    With MongoDB, in order to gain P, you sacrifice C. There are various ways to set it up, but in our application we have one master database, that all writes go to, and several secondaries (as can be seen from the diagram: M is the Master, the Rs are the secondaries – also called replicas, or slaves). Reads may come from the secondaries. So it is possibly that one or more of the secondary nodes could be disconnected from the application by some kind of network failure, but the application will not fall over because the read requests will just go to another node. Hence P.

    The reason this sacrifices C is because the writes go to the master, and then take some time to filter out to all the secondaries. So C is not completely sacrificed – there is just a possibility that there may be some delay. We are not allowing a situation where the secondaries are permanently out of synch with the master – there is "eventual consistency".

    So you might use this in applications where, for example, you are offering the latest news story. If User A gets the latest news 10 seconds earlier than User B, this doesn't really matter. Of course, if it was a day later, then that would be a problem. The failure case of C is just around the time of the write and you want to keep that window of consistency small.

    There is also a concept of durability, which you can also be flexible with.

    Take the following two lines of pseudocode:

    1. insert into table UNIVERSAL_TRUTHS (name, characteristic) values ('Anna', 'is awesome')
    2. select characteristic from UNIVERSAL_TRUTHS where name = 'Anna'

    What we're saying when we sacrifice consistency is, if I run these two lines on the same node then when I run line 2, I can be sure it will return 'is awesome'. However, if I run line 2 on a different node, I can't be sure it's in already. It will still be "eventually consistent" so if I run it later (and it hasn't been changed again in the interim) it will at some point return the correct data.

    However, you can also configure MongoDB to be flexible about durability. This is where, if you run the two lines of code on the same node, it might be the case that line 2 hasn't run, and possibly even never will. You might do this, for example if you were storing analytics. If you are looking for general trends, it might not matter so much if 1% of the transactions fail, so you might configure it to be flexible on durability. Of course you wouldn't do that for something as crucial as characteristics about Anna.

    What Should Your Work Log Tell You?

    15 April 2012

    We've got some great data for the SPA2012 workshop on JavaScript visualisations. Hibri has managed to obtained three years' worth of 7Digital's work-tracking data and Rob has very kindly allowed us to use it (anonymised, of course).

    We're going to use this dataset to show different information using different libraries for the visualisations.

    What I'd really like your input on is, what would you like to know? If this was your work-tracking data, what questions would you want it to answer?

    For example, we could create a Sunburst diagram using JIT to show what proportion of total development time is spent on the four different applications. We could create an interactive line graph using Raphael to show the average time a piece of work takes, and how that average has changed over the past three years.

    A little more info about the exact data is below, or feel free to skip straight to the example questions, or just go right ahead and tweet me or email me (at this domain) with what kind of information you'd want from a work log stretching back that far. You might get a great visualisation prepared for you to show just that!

    The Data

    Here is an example:

    "Feature ID": "A-321",
    "Application Name": "Project A",
    "Type": "Bug",
    "T-Shirt Size": "S",
    "Added": "15/03/2011 12:12",
    "Prioritised, Awaiting Analysis": "15/03/2011 12:12",
    "Analysis Completed": "15/03/2011 12:12",
    "Development Started": "15/03/2011 13:21",
    "Systest Ready": "15/03/2011 16:21",
    "Systest OK": "17/03/2011 10:34",
    "In UAT": "17/03/2011 10:34",
    "Ready For Release": "17/03/2011 10:34",
    "In Production": "17/03/2011 10:35",
    "Done": "22/03/2011 10:48",
    "Lead Time": "2",
    "Cycle Time": "2",
    "Development Cycle Time": "2"

    So this is a really rich dataset. We have all the dates that various stages of the release process happened, as well as some information about what application it was for, what type of work it was (e.g. Bug, Feature, Build Maintenance), what the rough estimate was (T-shirt size), and how long the whole process took, both from first raised to done (lead time) and from dev start to done (development cycle time). The log goes back to 2009.

    Example Questions

    Here are a few of the questions we've thought about answering.

    Your Chance for a Hand-crafted Visualisation Just for You!

    We'd love this workshop to be as relevant and interesting as possible, so please do let me know what kind of information you'd like to see visualised and it may well make it into the talk! Tweet me or email me at this domain. Thank you!

    P.O.A.

    20 February 2012

    My goal is to be a better developer.

    A few weeks ago, I had an appraisal. There was a lot of positive feedback and also some really useful suggested areas for development. With the help of my good friend and unofficial mentor Dolan O'Toole, I pulled together some practical suggestions as to how I could improve them:

    I then drew up a rough syllabus of the next steps I should focus on:

    I'd be interested if any of you have suggestions for additions to this? What should a great developer know?

    Would Have Been Useful to Know at My First Game Jam

    14 February 2012

    I had no idea what to expect at my first game jam, and I was nervous about whether I'd be able to participate. I'm a programmer, but I'd never written a videogame, and I don't even much play videogames.

    As it turned out, everyone was really friendly and welcoming and I was able to get totally stuck in. But there were a few things that I didn't know that everyone else seemed to know, and I was too shy to admit I didn't know too. Now, following my new and brilliant strategy of "ask as many questions as you can, the stupider the better" (more on that in a later post), I have managed to learn some of these things, and I'll share them here. They are the game engine, game mechanics, and a little bit about art.

    The Game Engine

    When writing video games, people talk about the "engine". For example, "What engine are you using?" and "Don't write your own engine; this is not 'engine jam' ".

    A game engine is something that handles the nuts and bolts of a game for you, which basically comes down to displaying the graphics, dealing with input (keyobard, joystick etc), and handling collisions. For example, in a game, when your player runs into a baddie you might want them to bounce off each other at an equal pace. Using a game engine means you can just specify the details of the collision. Not using a game engine means you have to write code to describe the angles and velocities yourself.

    Unity is a game engine that handles all this stuff for you. You can copy your art into the folder structure and then drag and drop it to where you want it to be. Game objects have default collision behaviour and you can just write a script to change it.

    Flixel is another game engine. It's a level below Unity – there's no graphical user interface, and you have to do a bit more work with the graphics, but the collisions, keyboard input and various other features are there for you.

    A Note on Writing Your Own Game Engine

    I didn't understand at the time why my second game jam was so much harder than my first, but when I explained what we did to the brilliant Joe Halliwell afterwards, it all became clear. We disobeyed the advice. We wrote our own game engine.

    To be precise, we used OpenGL, which is a 2D/3D Graphics API written in C. It gives the instructions to the graphics card – you definitely don't want to be doing that yourself – at least not in a 48-hour game jam. The code was written in Python, and for the binding we used PyOpenGL. For the physics we used Box2D. OK, so we didn't exactly write our own game engine from scratch, but we assembled one from various constituent parts.

    The alleged reasons were that we didn't know Unity, most of us knew Python (except for me – that added another layer of complexity to the weekend!) and between us we had two Macs, two Linux boxes and one loser running Windows. The real reason is that the brilliant Trevor Fountain loves this stuff and, if it existed, would sign up to 'engine jam' like a shot.

    Game Mechanics

    Another phrase I heard a lot and pretended to understand was "game mechanics". To be fair, I thought I did understand it – I thought it was jumping, shooting etc. I was wrong.

    Game mechanics are more like constructs of rules. Unlocking an achievement is a game mechanic. Going up a level when you reach a certain number of points is a game mechanic. Dying when you lose 90% of your health bar is a game mechanic. So when someone asks "What are the game mechanics?", they mean something like, what are the gamey things here? What makes this a game, rather than just graphics moving across a screen?

    I like this list of potential game mechanics.

    A Little Bit About Art

    While I'm here, just a few words on pixel art vs vector graphics, something else I heard talked about which added to the background radiation of feeling I didn't quite understand what was going on.

    There's an extremely detailed article on the differences here but in very brief summary – technically speaking, pixel (aka bitmap, raster) art is basically dot-matrix, i.e. made up of pixels individually coloured, and vector art is created using mathematical functions and is basically points and the lines joining them. The art for your game may be either, or some combination of the two. A brief rule of thumb is that old games tend to use pixel art, but the choice is up to you – different tools for different times.

    However, it's more than just the technical differences, and the conversations you hear about pixel vs vector art will probably reflect something other than the strict technical distinction. Trevor summed it up for me very clearly, so here is an edited version of what he said:

    "To me, pixel art is more of an aesthetic choice than a technical term. It's true that older games had a pixel art aesthetic, especially on 8- or 16-bit platforms. Today, though, I think people use the terms 'pixel art' and 'retro' more or less interchangeably – games like Canabalt or The Last Rocket are undeniably retro, and use the pixel art style to great effect. Games like Angry Birds are rendered using the same technology (2d sprites), yet no one would ever say that Angry Birds qualified as pixel art.

    "As for vector art, true vector images (e.g. svg) are rarely used outwith UI design and Flash."

    Next steps

    How to Make Your First Videogame by the excellent v21 is great, and the short video You Can Make Video Games is fab and really worth watching. Or why not just sign up to the next Global Game Jam?

    Enjoy!

    JavaScript Talk Takes Shape

    21 January 2012

    Just over a week to go until the final deadline for the SPA submissions, and the JavaScript visualisations talk is shaping up.

    The plan is to demonstrate the use of a JS library to produce a certain kind of visualisation, followed by a 15-20 minute exercise where participants use the library to create a similar visualisation. I've said "rinse and repeat 4-5 times", though I'm slightly dubious as to whether we're going to have time to do more than three. Hibri and I are going to do one each and demo to the other, so we'll have a better idea then of how many we can cover. I'm really excited about what we're going to produce!

    At the moment we are planning to try and do:

    Is there a type of visualisation you'd really like to see us demonstrate, or a library you think we can't miss out? Please do let me know.

    There is also still time to give feedback directly on this and all other proposals for SPA 2012 here (SPA login required).

    Preparation Begins for the JavaScript Talk...

    18 December 2011

    As part of preparing the proposal for the JavaScript visualisations talk, I had a coffee with Ian Alderson. He did an excellent talk at SPA2011, along with Adam Iley, on HTML5. The presentation is still available online (using HTML5 for the slides!) here, I really recommend you check it out.

    Although Ian doesn't have time to co-pilot on the talk, he very generously gave up his time to give me some advice. Notes below. The first suggestion of his that I plan to follow is a comparison between SVG and Canvas – as he pointed out, all JS visualisation libraries will be based on one or the other, so that will definitely be a factor in what library to choose. It's not the case that one is just better than the other – both have strengths and weaknesses. Watch this space for more on this topic...

    JavaScript Visualisations Proposal

    30 November 2011

    I have proposed a talk for SPA2012 on JavaScript visualisations.

    The basic outline of the proposal is a workshop where we will demonstrate the use of different JS libraries to visualise different kinds of data with several 15-20 minute exercises where participants use the library to create a similar visualisation. Ideally participants would leave with an overview of how and when to use the libraries and tools we've covered, and ideally an idea of what factors to think about when choosing a JS data visualisation tool.

    Still in the very early stages of planning it, but I am in the process of moving this site over to a host that will support WordPress, at which point I will be able to invite comments/suggestions. In the meantime, any suggestions are very welcome, by email or twitter.

    Notes from the first planning meeting, with Hibri:

    My Continuing Struggles with Linux

    17 October 2011

    Summarised excellently by this cartoon. It's great fun, but...

    Sorl-thumbnail Comes Back to Bite Me

    12 September 2011

    Well, the lack of sorl-thumbnail came back to bite me when I got the latest version of the Django project I've been working on. Previous releases had lulled me into a false sense of security, but then the latest update, a bit too late in the evening, I had that old error:

    ImportError: No module named sorl-thumbnail

    So off I went again. I had no problem downloading sorl-thumbnail but everywhere I went wanted to put it into the wrong directory. It's not in the Synaptic Package Manager, and I couldn't find a PPA. Just to make it a bit more exciting, the dependency of the project I needed it for was something like version 3.2.5. The current version is 11.0.4.

    Ideally what I wanted to be able to do was set some kind of flag on the install that told it to install somewhere else. Surelly there is a way to do that? But I couldn't find it. I had got as far as actually (again!) RTFM, and was browsing through the Core Distutils functionality page when lo and behold, I stumbled upon this. Not directly relevant you might think – but wait, item 13? What's this?

    Yes, to cut a long story short, I had discovered symlinks. New to me, old to everyone else. It was short work to set one up, helped by this, and lo and behold: it works.

    Kind of begs the question as to why I didn't do that in the first place for all the packages... but never mind. Onwards and upwards!

    How to Write Efficient CSS – Evaluation of CSS

    29 August 2011

    I recently did a knowledge share at work on how to write efficient CSS, and one of my colleagues – a senior developer with a lot of experience – said "I felt the penny drop". High praise indeed, so I thought it was worth reproducing it here.

    The write-up is pretty long, so I've divided the divs into Basic CSS in which I cover:

    1. CSS
    2. Selectors
    3. The Cascade
    4. Inheritance
    and Evaluation of CSS in which I cover how CSS is evaluated and some things we can do to make it more efficient.

    How CSS is Evaluated

    The key information is these two points:

    1. For each element, the CSS engine searches through style rules to find a match.
    2. The engine evaluates each rule from right to left, starting from the rightmost selector (called the "key") and moving through each selector until it finds a match or discards the rule.

    1. For each element, the CSS engine searches through style rules to find a match

    The style system breaks rules up into four categories by key selector.

    1. ID Rules – for example button#backButton { ... }
    2. Class Rules – for example button.toolbarButton { ... }
    3. Tag Rules – for example treeitem > treerow { ... }
    4. Universal Rules – all other rules

    The CSS engine then takes each html element in the document in turn. If it has an ID, then the engine searches through the style rules and checks rules that match that element's ID. If it has a class, only Class Rules for a class found on the element will be checked. Only Tag Rules that match the tag will be checked. Universal Rules will always be checked.

    2. The engine evaluates each rule from right to left...

    So in the example button#backButton { ... } the key is the id "backButton". In the example I give in Basic CSS the key is the class "blog-post".

    The engine starts with the key and then evaluates the rule from right to left. So if you have a button with an id of "backButton", the engine first matches the id to the id and then compares the next selector – is the element a button? In the example from Basic CSS the evaluation for the second selector, ul#nav.dhtml li a.blog-post, is as follows. Does the element have a class of blog-post? If so, is it a link? If so, is there anywhere in its ancestry a list item? If so, is there anywhere in the ancestry of that list item an unordered list element with a class of dhtml and an id of nav?

    You may be getting a slight clue now as to why I think that selector is inefficient.

    Recommendations

    There are some obvious ways we can start here.

    These are just recommendations as to how to write the CSS. If you care about your website's performance you should already be minimising and gzipping your CSS. So how much of an edge will these recommendations give you?

    CSS and Performance

    CSS and performance is a fairly hot topic right now, especially with all the cool things that you can do using CSS3. Dave Hyatt, architect for Safari and Webkit, said "The sad truth about CSS3 selectors is that they really shouldn't be used at all if you care about page performance." (The comment can be found here).

    That's certainly something I've heard, for example at conferences. However, another web giant, Steve Souders (works at Google on web performance) has a different opinion. It's worth reading the piece in full (there are charts and everything!), but the takeaway here is: "On further investigation, I'm not so sure that it's worth the time to make CSS selectors more efficient. I'll go even farther and say I don't think anyone would notice if we woke up tomorrow and every web page's CSS selectors were magically optimized."

    So why am I bothering with this? Well, a few reasons. One is I think it's always worth taking the time to find out how things work and I'm glad to be able to make a reasoned judgment on this.

    But also, there are various things to consider when thinking about writing efficient CSS. There is performance, obviously, but two other major concerns are ease of writing and (in my view more important) ease of reading. I love clean code, and I think it's crucial that code is easy for other developers to read. I'm not sure I care whether or not ul#nav.dhtml li a.blog-post is performant or not, it's certainly not clean, and it took me some brow furrowing to work out when it would apply. So personally, I'm going to follow the rules I've outlined above. What do you think? I'd love to hear your opinion.

    Useful Further Reading

    I gleaned most of the information about how the CSS engine works from Page Speed documentation and the Mozilla blog. I couldn't find any information about how IE evaluates CSS, please do let me know if you have any.

    To take things further with writing nice CSS, you could look at Compass/SASS, or my current favourite, OOCSS.

    How to Write Efficient CSS – Basic CSS

    06 August 2011

    I recently did a knowledge share at work on how to write efficient CSS, and one of my colleagues – a senior developer with a lot of experience – said "I felt the penny drop". High praise indeed, so I thought it was worth reproducing it here, even though other similar divs are available on the internet.

    The write-up is pretty long, so I've divided the divs into Basic CSS in which I cover:

    1. CSS
    2. Selectors
    3. The Cascade
    4. Inheritance
    and Evaluation of CSS in which I cover how CSS is evaluated and some things we can do to make it more efficient.

    CSS

    For those who have no idea at all what CSS is, I can recommend nothing better than the w3schools excellent intro. The w3school is always my first port of call for definitive answers on html, CSS and JavaScript. I will assume that you at least know that CSS stands for Cascading Style Sheets, and realise why separating that from html can make development easier.

    Syntax

    CSS is applied to html elements using selectors. The syntax of CSS is:

    selector { CSS property : value; }

    If you want to add comments, use /* comment */ as C-style comments (//) will cause your CSS to fail silently – all you'll see is your website looking wrong.

    Let's look at some more details of how CSS is written.

    a.blog-post, ul#nav.dhtml li a.blog-post {
    display: block;
    float: right;
    height: 24px;
    width: 24px;
    margin: 3px 3px 0 0;
    padding: 0 0 0 0;
    background: url(../images/film_help.png) no-repeat;
    }

    1. Padding and the box model

    2. If you've ever worked with CSS at all, no doubt you have fiddled around changing the padding or the margin without actually knowing why. I certainly did. Until I saw this diagram, which suddenly made everything clear:

      Have a look at the page on w3schools, but basically the margin is how far the box is from other elements, and the padding is how much space you'd like between the inside of the box and the content. Genius. And obviously, although not given in the CSS example above, you can manipulate the border too, as I have done in my code samples on this page, for example border-style: dashed;

    3. Padding and Margin shortcuts

    4. It is possible to specify each direction of the padding, for example padding-left:3px. However you can also use a shortcut, as has been done in the example. The order is like a clock: Top, Right, Bottom, Left; so an element with the CSS in the example applied to it will have a margin on the top and the right. Another way to remember this is by remembering that if you don't get it right there will be TRouBLe. :o)

      However, you can make it even shorter than that. Three values set the top to the first, the right AND left to the second and the bottom to the third. For example:

      margin:10px 5px 15px;
      top margin is 10px
      right and left margins are 5px
      bottom margin is 15px

      Two values set the top and bottom to the first, and the right and left to the second, and one value sets them all to the same. Here if you didn't follow that.

    5. Ems

    6. Sizes can be given in pixels, ems or percentages. Pixels you know. Percentages are as a percentage of the enclosing elements (see inheritance). Ems are also calculated as percentages, where the default for most browsers is that 1em = 16px. However (of course) there is a slight twist in that ems are not calculated correctly in IE, so .85em is smaller than 85%. The w3schools recommendation is to use a combination of percentages and ems. The developer tools are invaluable in this respect and there is a useful discussion here.

      In the meantime you might want to remember this hilarious joke: Q. What did one em say to the other em? A. Who's your daddy?

    7. No-repeat

    8. A brief word on the image. background: url(../images/film_help.png) no-repeat;. The url is a link to where you have stored the image. no-repeat means you want it to appear once. The default is for it to repeat both horizontally and vertically. A nice trick for filling in a background is to create a slim image with the gradiations you want and then repeat-x so it fills the div.

      An aside: another way to include images is to instead use a data url. This is where you encode the image inline. The advantage of this is that it doesn't require an extra HTTP request to get the image, and the key to a faster website is minimising the HTTP requests. However, there are reasons (other than the ubiquitous incomplete cross-browser support) why you might not want to use data urls – a good discussion can be found here. Other ways to minimise the HTTP requests associated with loading images can be found here.

    9. Optional;

    10. The last semi-colon is optional. In fact, the structure of a CSS class is selector { CSS property : value } – you only need the semi-colon if you have subsequent instructions. I always put it in anyway though, there's no reason not to.

    Selectors

    There are loads of selectors in CSS. For now, I'll just talk about the most common:

    html element

    For example, p { color: red; } would make all text in paragraphs red.

    #id

    Giving the ID makes the one specific element behave in a certain way. It is certainly the most efficient selector (see how it's evaluated, but it isalso slightly pointless. The point of style is to make a website look and feel consistent – with your brand, with itself, etc. IDs are (supposed to be) unique on a page. So why would you want to style just one thing?

    .class

    The most common selector and the one I think we should all be using most of the time.

    *

    The universal selector. Some interesting discussion here, but in summary it is the least efficient selector and also allows you to bypass inheritance. I say AVOID.

    Combinations

    x, y

    This means, apply the style you are outlining to all xs and all ys. For example p, .blog-intro { font-weight: bold; } makes the text in all paragraphs bold AND the text in all elements with the class "blog-intro".

    x y

    The descendant selector. This matches any y which is a descendant of any x. For example p .blog-intro { font-weight: bold; } makes all the text within a paragraph that has the class of "blog-intro" bold – even if it is nested several layers within. It is very inefficient. See later post

    x > y

    The child selector. This matches any y which is a child of any x. This is also inefficient, though less inefficient than the descendant selector.

    a.blog-post, ul#nav.dhtml li a.blog-post

    So, to return to the selector in the example which I have so far ignored.

    To spell it out, the style outlined here will be applied to any link with the class of blog-post, AND any link with the class of blog-post which is a descendant of a list item which is itself a descendant of an unordered list with the id of nav and a class of dhtml.

    Pretty complicated. Over-complicated, I will argue. But just to note – the reason you might want both of these (you might think the first would cover the second) is because you may well have one or more intermediate styles that have altered the link in the list item further. For example if you have styled ul#nav.dhtml differently, the link will appear differently unless you reset it here.

    In my view, examples like this are why people do not like CSS. Oh, and this is a real example from a live application, by the way. Names slightly changed to protect the innocent.

    The Cascade

    As hinted at above, you can have multiple styles applied to an element, and the cascade is what determines which one is actually applied. CSS styles are cascaded in the following order, with the one applying last being the one that sticks:

    1. Origin (i.e. Browser then Author)
    2. Importance (normal vs !important)
    3. Specificity
      1. Inline
      2. Highest number of id selectors
      3. Highest number of class, attribute, or pseudo classes
      4. Highest number of elements and pseudo elements
    4. If still the same, the order in which they appear.

    Here for (very dense) more.

    Specificity

    Selectors are considered to be specific in the following way (ordered from the least to the most specific):

    1. The type selector
    2. The descendant selector
    3. The adjacent sibling selector
    4. The child selector
    5. The class selector
    6. The attribute selector
    7. The ID selector
    Here for more.

    Order

    The order, listed from the least precedence to the most precedence:

    1. Browser default
    2. External style sheet
    3. Internal style sheet (i.e. written in the head)
    4. Inline style (i.e. inside an HTML element)

    Notes:

    An external stylesheet will override an internal stylesheet if it's linked to in the head after the internal style sheet.

    And the most common trip-up in legacy code systems: The same class within a CSS file will override one written higher up in that file.

    important!

    You will have seen that important! takes precedence in the cascade. This is what you add if you can't get the style you want using the normal rules of cascade and inheritance. Don't use it unless you really have to – to me, it says "I don't know how CSS works so I'm just going to hack it."

    Developer Tools

    All modern browsers have developer tools so you can examine elements to see what CSS is being applied, and in a surprising departure from the norm, the best one in my opinion is the one available in IE when you press F12.

    For example, in this screenshot you can see that the colour being applied here is the one from the class ul.dhtml#nav not the one specified for body or the one specified for body.mainframe.

    Inheritance

    I could not do a better job of writing up inheritance than this company presentation. I really recommend you go and click through it. It starts very simple and you may think it's a waste of your time but if you are not 100% sure how inheritance in CSS works then this will really help.

    A brief summary though if you really can't be bothered: Elements inherit styles from the elements within which they are nested. So in the following html, if you apply a style of font-weight: bold to p, then the text inside the span will also be bold.

    ‹body›
    ‹p›I'm bold. ‹span›And so am I!‹/span›‹/p›
    ‹/body›

    Read on for how to write it efficiently!

    A Voyage of Discovery – Upgrading Firefox Part 2

    27 July 2011

    Right, it turned out my next step was not a chat with Joe Halliwell but instead with my good friend and mentor, Dolan O'Toole, and what I thought might be a voyage of discovery into how to make my installation of firefox run like a normal program turned out to be just a short trip of discovery to finding out that I hadn't actually been looking in the right places.

    After helpfully pointing out that I "sound like a linux newbie :)" (yes, yes I am), Dolan explained where I'd gone wrong: "You followed the instuctions as they are. The only thing you weren't aware of is that most of the time, someone would have done a build of a program for ubuntu and put it in an apt repository, usually on launchpad. I usually search for something like "firefox 5 ubuntu 10.10" if I need to install something before I resort to manual installations."

    Good tip, and here it is:

    http://www.webupd8.org/2011/06/firefox-5-lands-in-firefox-stable-ppa.html

    So – I have learned that it's not quite as straightforward as finding the instructions and then following them – you also have to know stuff. That's OK though. And at least I have firefox the way I want it now. I'm sure there'll be another opportunity to get my hands dirty...

    Upgrading Firefox – part 1...

    20 July 2011

    So. Not content with the Ubuntu version of Firefox which is at 3.6.18, I decided that I wanted Firefox 5.0. Heck, I want 5.0.1.

    So I followed these instructions.

    To no avail. I followed them to the letter (or so I thought), but when I finished up by running firefox, to my joy, Firefox popped up, and to my moments later horror, it was still 3.6.18.

    Why??

    Well, lots of reasons why, as I discovered when I unistalled Firefox 3.6.18.

    First of all, when it said "Run the following shell script" I just typed it into the console window. That did not work. Don't sigh, I'm new to this!

    So I created the shell script and saved it. Following, incidentally, instructions here – the bit I was missing was the permissions: chmod +x myfirstscript.sh

    [NB. I couldn't agree more with the grateful commenter on that link: "Everybody just writes "run the shell script" but a complete beginner doesn't know, that shell scripts have to be executable and are started with ./"]

    OK I've run the script woo hoo! "The firefox command in your ~/bin directory will now run Firefox with the mozilla-build profile." I have the file, the file contains another script, that script should allow me to start firefox, right?

    Wrong.

    bash: /usr/bin/firefox: No such file or directory

    Well that, presumably is why running the firefox command before started up the old firefox. (So – hey – I could have just run the script in the command line like I wanted!)

    So, I decided to roll back a step and delete the new ~/bin directory – I didn't like it anyway. I discovered I could actually run Firefox, from the firefox directory, by running this command: exec "/home/anna/firefox/firefox" -P mozilla-build "\$@" . So I wrote a shellscript to do that.

    So now I can run firefox. It's 5.0.1. But I have to run it from the command line. Closing Firefox doesn't close the terminal window, but that terminal window is taken up with running firefox (maybe there's a way round that like with gedit &).

    A few other things. The firefox running remembers passwords. It remembers what I've set my home page to. But it doesn't start up on the home page even though I've asked it to. Agreeing to restart it does so. Behind the scenes, there are a couple of errors:

    (firefox-bin:1923): Gtk-WARNING **: Loading IM context type 'ibus' failed (firefox-bin:1923): Gtk-WARNING **: /usr/lib/gtk-2.0/2.10.0/immodules/im-ibus.so: wrong ELF class: ELFCLASS64

    Ideally I want this firefox to run normally, i.e. be available on the menu, have an icon in the top panel, not to rely on a command window. I suspect my next port of call is to discuss this with Mr Joseph Halliwell. I hope there will be a part 2 where I turn out to have learned loads about this area!

    What I have learned about folder structure today

    22 April 2011

    Easy_install (as it comes) doesn't work for Debian-based systems.

    The default behaviour is to install things to /usr/local/ – this is the Gnu default – whereas the synaptic package manager installs things to /usr/. I imagine there may be a way to reconfigure the default behaviour, but I didn't get that far.

    This is how I found out this rather useful piece of information. I had installed easy_install, and then used it to download all the dependencies I needed to get started with this python/Django project I was going to work on. And then – nada.

    For about three hours, no matter what I did, I had this message:

    File "/usr/local/lib/python2.6/dist-packages/Django-1.3-py2.6.egg/django/db/backends/mysql/base.py", line 28, in from django.db import utils ImportError: cannot import name utils

    My friend who was with me, trying to get me set up to start work on the project, is a Django expert, but he uses Windows. Hey, so do I! What am I even doing using linux? (See sidebar for answer...)

    We tried a lot of things. I won't go into them all here, mainly because I can't remember many of them. We tried a lot of things that people on the internet had suggested. As a last resort, we even tried to RTFM. To no avail.

    After we'd given up and my friend had left, I went back to it to try and figure out what was going on. I even tried to resort to the beginner standard of adding log messages, but all the files I wanted to edit were read-only. Finally, this page offered me a glimmer of a clue.

    Specifically, the question "Where are my site-packages stored?" and the answer:

    python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"

    Which for me, returns /usr/lib/python2.6/dist-packages

    Hang on though, the error is in /usr/local/lib . . . eh?

    A visit to the python2.6 folder in /usr/local confirmed that all of the stuff I needed was in there. And a call to my incredibly helpful and talented friend Joe Halliwell confirmed my growing suspicion that this was Not Correct. He explained to me the Gnu/Debian folder structure differences.

    So, I backtracked. I installed everything I needed (except sorl-thumbnail, which wasn't there. However, all I need to do is find a ppa. There is probably also another way to install it correctly. By the time this is all done, I may even know what it is.)

    I ran through a few errors on the way, but all of the ImportError: No module named django_extensions variety, and solved one by one, satisfyingly, by installing what I needed in the correct way.

    Finally, several hours after my friend came round to work on this, I now have a new error:

    File "/usr/lib/pymodules/python2.6/MySQLdb/connections.py", line 170, in __init__ super(Connection, self).__init__(*args, **kwargs2) _mysql_exceptions.OperationalError: (1045, "Access denied for user 'anna'@'localhost' (using password: NO)")

    It's progress.