A few months ago, we started complaining seriously about the Rails assets pipeline. We did everything we could to bypass some problems, fix others, speed up deployment, compilation or precompile. We had to find an alternative that would work and actually improve the development process. This is not a story about how we decided to replace a Rails component. This is a success story about how we managed uncertainty in an Agile way.

As the application grows, the challenges or problems are growing too. And it’s not always possible to define stories for a proper scrum, Kanban or any other agile method. If a story can’t be defined precisely, it’s almost impossible to estimate when there is too much uncertainty. As a developer, you don’t want to commit to a 21 points story in a sprint when you don’t even know if it is feasible in the first place. That’s when you do spikes.

Our team has a very special agile methodology. We’re improving our process continuously (well, you’re supposed to if you are agile) and we ended up with a mix of Scrum and Kanban. We don’t have artificial deadlines with sprints but we still estimate stories with poker planning. We also love our carefully chosen tools to help us organize, communicate and achieve work without friction. So spikes fit in our process in a very powerful way. But we had to define clearly what is a spike, what is its goal and how to complete it.

What a spike is is pretty universal. In the image above, “learn about Kanban” and “try Kanban tool” can be considered spikes. Other real-life spikes examples would be:

  • Is switching to a CDN worth it?
  • Should we convert all our javascripts to coffeescripts?
  • We know we will reach the limits of that system soon, what should we do to avoid apocalypse?

I like to define it as “time dedicated to investigate and document”. Basically, answering those questions will mitigate risks and reduce uncertainty.

The way they are integrated in our flow is pretty simple. As chores, spikes are not given complexity points. Instead, they get an amount of time. It could be half an hour or two days. It’s what is reasonable to invest in. And it is prioritized as any other story. So a spike can only begin when higher priority stories are done and must be done before lower priority ones. I know, it’s trivial. But still, it’s important to follow those guidelines to avoid losing track of where the team’s resources are spent.

So, we know how much time to spend on a spike and when, but what will be produced? Since the work done in a spike is about searching, trying and making mistakes, it is very important and valuable to everyone to document the progress. When a spike is left there because we ran out of time, we should be able to come back to it and see what has been done in detail. If your project qualifies for a government R&D tax credits program, that documentation will simplify the application and has so much value when verified. Your managers will love it.

So, the goal of a spike would be to produce knowledge and to reduce uncertainty. So, it’s important to follow some guidelines to make sure that the knowledge is communicated. This can be very useful for every level of development and management. So, here is the questions to be answered (and documented) in the time allocated:

  • What is the problem that we want to solve?
  • Is it feasible?
  • How much effort does it need?

When the conclusion is that it is possible and the amount of effort is defined, the knowledge produced and documented should be enough for the product owner to create the stories to do the real work and help the development team to estimate it.

Documentation guidelines

In the case of replacing the Rails assets pipeline, the question was already asked in person and we discussed about it in different situations: before creating the issue, in the poker planning meeting, in the issues related, in informal discussions, etc. To get the big picture, to be able to communicate it, demonstrate its value and what was invested and what will eventually be invested, we have to define clearly what has to be answered. We should start documenting what was done prior to the spike, what are the specific problems and what kind of solution do we value. That approach is “creatively inspired” by some parts of the scientific method.

Write a summary of what’s been discussed

This is simply to communicate what motivated to get into that spike instead of “just doing X or Z”. X or Y might have unwanted consequences and we have to communicate it. Or maybe the goal of the spike has so much value that X or Y would be a waste of time before we finally try what’s in the spike.

Document your steps

What’s cool about a spike is that you are autonomous and trusted to make important decisions. Those decisions are important and might have a major impact on the team. For example, if I decide that the best approach is to change Sprockets for Gulp, we’ll all have to learn the new way of creating and managing assets. Document what were your alternatives, why you made the decision and how that will affect (positively and potentially negatively) the team and the project. That will also be useful if the spike runs out of time and we want to come back to it later. That important knowledge won’t depend on one developer’s memory. It will be here forever and anyone will know where to start. It can also be valuable if your project qualifies for any government R&D tax credits program.

Answer the three questions explicitly

The goal is to answer them. So write them down in a way that is easy to spot immediately. Use titles or bold text to make them even more obvious. I like to write them down in order in the conclusion. It is also a summary of what will be useful for the next steps and they can contain short “pros and cons”, a list of caveats or other possible alternatives found. Keep it short, but very dense in information.

Abuse your tools

We document our spikes in Github because it’s where they are defined. They are simply GitHub issues and we use ZenHub to estimate, prioritize and move them on an agile board. So, at every step, we document via rich comments, links, images, and any other GitHub feature. We don’t need another software or web app and we like to keep everything at the same place. Your documentation should be easy to find. You should not try to over engineer the flow and lose time just to start documenting. As in development, it is easy to break the research flow. Your focus is more important than some fancy feature of a new tool.

Use Markdown

  • Markdown is cool.
  • Markdown is so fast to write
  • Markdown is simple
  • -> You don’t lose time formatting it. <-
  • It is nice to read
  • it’s an effective tool to communicate with bullet points, lists, titles, links, etc.
  • You can create yourself templates to fill

That point is also to emphasize on the importance of your focus. Of course you can use another format or a document editor or Google docs. But don’t do it at the cost of your flow.

The definition of “done” and “success”

When is a spike “done”? When time’s out? When all the questions are answered? The answer is, whichever comes first.

If the time runs out, “we don’t know yet” is a perfectly acceptable answer to “is it feasible?”. But you still have to produce the documentation on what you tried or learned so any other team member could continue if it is decided to resume the spike. If you have some kind of code review process, you can totally have the same process to review what documentation has been produced. Because we are using Github, we can comment, ask questions and suggest edits to improve the documentation of the spike.

Done does not mean success. Success means that we can make a decision based on the conclusions.

Spike: Should we use a CDN to save money?
Answer: No.
Our servers resources are underused right now (insert graph here). A CDN would be additional infrastructure costs and development is needed.

That spike is a success. Even if the answer is no, we have knowledge about that problem. We will maybe know how much third party CDN cost, when we will reach the point that a CDN will save some server resource and what is the development effort will be.

The way you include spikes in your flow is up to you. But documenting a spike requires some rigor. I started using those guidelines for myself and I got immediate positive feedback on my work. I decided to document them for my team and we saw immediate benefits for it. Defining a spike got easier. The time spent on a spike is more valuable. Deciding how much time to spend is also easier.

Share this post if you think it could be useful for your team or developer friends. Your product owner will owe you a high five. If you have similar guidelines or you do something that we should try, please, send it to me. We always want to improve our process.

Here is a gift, just for you my friends:

You’re welcome.

@sophiedeziel / Ruby on Rails developer @ Shopify / trying to write relevant things / eating flying spaghetti monsters / trying to travel more

@sophiedeziel / Ruby on Rails developer @ Shopify / trying to write relevant things / eating flying spaghetti monsters / trying to travel more