Eating our own dog food – a year of decision logs

Loqbooq is not our first rodeo and frankly, rodeos aren't a good metaphor either. We have created and still maintain several app projects like Tincta – now in its 10th anniversary – and Wokabulary. But we have also been working in other teams on a diverse portfolio of products. So, we are more used to running marathons in a software development kinda sense. You know, staying long enough to ~~become the villain~~ see how your decisions worked out and hopefully learn from your mistakes.

Insufficient facts always invite danger (Spock)

To illustrate why writing down decisions is important, let's start with a quote by Admiral Hyman Rickover (who with his team designed the first nuclear submarine in just three years) from a speech he gave at Columbia University in 1982:

When important decisions are not documented, one becomes dependent on individual memory, which is quickly lost as people leave or move to other jobs. In my work, it is important to be able to go back a number of years to determine the facts that were considered in arriving at a decision. This makes it easier to resolve new problems by putting them into proper perspective. It also minimizes the risk of repeating past mistakes. Moreover if important communications and actions are not documented clearly, one can never be sure they were understood or even executed.

Not sure what else needs to be said about this, but have you ever been in the situation where you would have liked to simplify a system but you didn't know if the current state was due to rapid prototyping experiments or because of real business requirements and the people who knew had long left the company?

Anyway, of course people know of the importance of documentation, it's just not something that is overly fun. So indeed, in projects we’ve worked on over the years we did see some attempts at documentation. Sadly, most documentation emphasized the 'What' and left out the 'Why'. Additionally, the documentation was not always accessible to all team members. Comments in code, for example, are pretty invisible to most designers and managers.

Storytime!

Being aware of all those problems we set out to create a tool to lower the barriers to document all the 'Why' in projects while being approachable to all team members, too. Naturally we started to use Loqbooq ourselves as soon as possible. In fact, the main development and reasoning behind decisions taken on the way while developing and releasing Loqbooq is documented in Loqbooq. Here is a short retrospective about the process and how it worked out for us.

It’s a… decision

Starting something new involves a lot of discussions, brainstorming and finally decision-making even before a line of code is written. For Loqbooq, we first spent a not insignificant time to narrow down the scope that left the final product usable but also would enable us to implement it in reasonable time. While originally Loqbooq was meant to be a Slack-only app, hoping this would reduce implementation time, it became clear this would limit the scope of addressable users too much.
A decision was made for the broader audience and we wrote it down in Nuclino, the knowledge base we use. I'm glad we did, as you will see later.

We also had to define our target user group, our assumptions about them and why we chose this group. Another very important decision for everything that comes afterwards.

Next, we asked ourselves which programming language, web-framework, database and hosting solution would enable us to quickly develop something functional.
Developers, being only humans, tend to involve some of their own ego when considering solutions for their tech-stack. Personal interests not seldom overrule sensible decisions. We wrote down our reasoning and crossed out alternatives with good arguments against them. This was probably the first time in this particular project where writing down the decision really forced us to be rational.

We’re not tooling around

Mind you, up to this point Loqbooq is far from usable. Instead, someone had to take notes or the main points from the discussion in Slack over to Nuclino, copy everything in a template and finally, if we weren't able to decide on the spot, remind everyone to add their agreement or proposals. How tedious to just document a little bit of 'What' and 'Why'. The same held true for looking up decisions taken in the past. Definitely something to improve.

The rubber meets the road

Fast-forward a few weeks and many decisions later, Loqbooq is finally usable and we decided on naming conventions for our domain model, colors for branding, and the fact that we support Slack's enterprise grid for the release. Reminders are sent out automatically and recording decisions happens right in Slack. This is directly reflected in the way we document the decisions: before, we only noted down big decisions with many considerations, like deciding on the whole tech-stack is all in just one decision. Now, even smaller things are documented or big decisions are split up. Something like our pricing model stretches over six different decisions, e.g. what happens with accounts that are late for payments, how long should the trial phase be, etc.

Around the same time it became clear that we would miss our aspired release date by at least a few weeks. The complicated (and frankly, insane) way Slack's enterprise grid is implemented from a data model perspective slowed us down and supporting all functionality with a web app suddenly felt like an additional burden. Thankfully, our documented agreement on our domain language helped greatly navigating through Slack's and our own data model and their interaction.

But, what about all the work on the web app that was still waiting for us? We really wanted to release and time was ticking. So when I brought up the discussion in the team, questioning our direction, we quickly looked up the context and reasoning of the former decision about not just doing a Slack-only service. With that we were able to re-evaluate if we were still doing the right thing (spoiler: we released Loqbooq with a proper web app).

In hindsight, I'm glad we had the documentation of 'Why'. It enabled me to get rid of doubts and concentrate on taking the project forward, reducing the mental overhead significantly.

The same goes for our pricing model. Initially we went for a rather short trial phase and a one price fits all model. In the meantime we re-evaluated our decisions and since we documented the ‘Why’, we were even able to learn something. See our blog post.

One take-away to go, please

So now, after more than one year of consistently using a decision log, I have made some observations. Not all of them I merely attribute to the decision log itself but also to our practice to take decisions together. Which definitely is fostered by maintaining a decision log.

1. Reduction of recurring discussions. When we are unclear about why and what exactly we decided on a certain matter, we can now often just look up former decisions. And when we realized we are talking about the same topic twice, we create a new decision on it.

2. Increased feeling of ownership for the good but also the bad parts of the project. We took decisions together, but that means we also agreed together on where to take shortcuts.
   Imagine starting at a project and soon enough you discover parts that feel messy and slow down development of new features. How soothing it would be to know why they are there. Maybe the project's scope changed, maybe some deadlines were too tight, maybe it's just some mess that needs a good cleaning.

3. So much learning. To learn you need a feedback loop, the faster you get feedback, the better. Sadly not all consequences become clear right after the action, to learn in that case, you need to be able to go back and look up the context of your decisions.

4. Ease of mind. Writing down and documenting decisions together with the considerations you and your team had frees up parts of your brain. Sometimes it just helps to be forced to really formulate a decision.

5. Improved communication. Since we decided together, we also had to discuss problems and possible solutions together. We had to actively argue about moving forward. As a very nice by-product, we also got rid of the feeling of others deciding over your head while you have to deal with the damage.

6. Additional documentation. Unlike with fast prototyping and other very short-lived projects, longer running projects need a certain documentation about intent, current available knowledge and context. Contrary to what is often seen, agile project management still involves having a plan (see: Rich Hickey), only the plan can be adjusted and changed. So, in long-living agile projects, it's not trivial to comprehend the reasons for the state of the project. In this case, decision logs can support or even replace requirements specification.

Not all glitter is gold

Maintaining a decision log is work and needs practice and learning. As you can imagine, not everything worked right away, but every obstacle is a opportunity for improvement.

1. Sometimes we forgot to log decisions. Ultimately this is not a big deal, the next time you have a discussion about the particular topic, you will remember.

2. When in need of short-term approvals, outstanding decisions can block implementation. This happened mostly when we didn’t plan properly and needed some ad-hoc decisions and involved team-members weren’t available right away. In those cases, we went with some kind of majority but still leaving the decision open until the team members had a chance to review them.

3. Occasionally we had discussions about wording in decisions. While annoying at times, it also often pointed out different understandings that needed clarification.

It’s all about the seasoning

Decision logs are a very helpful tool for a more sustainable software development. Even if it's yet another thing to do, maybe even annoying at the moment, in the long run it helps to be able to go back and look at why things are as they are. But more than that, decision logs also foster communication and speed up the decision process by enforcing a written formulation. Last but not least, decision logs increase the sense of ownership if they are maintained together in a team.

Having a decision log is for project management a bit like having tests in your code base. It increases the sense of security in ever-changing, agile projects. Going back, having a look at the context of a decision and its reasoning can reduce disgruntlement over the current situation, too. While technically you don’t need to use tools to maintain a decision log, they can help you lower the barrier of adoption and improve the quality of the log.

We as a team have found decision logs very beneficial and adopted them in basically all areas of our business.