You must think first, before you move.
In a recent post, a colleague of mine in Kainos where I currently work, Davey Mc Glade implored us all to consider the implications of any decision you make.
As immortalised by the Wu-Tang clan in ‘Da Mystery of Chessboxin’…
Sage advice indeed. Let me give you a means to do so.
Open Design Proposals (ODPs)
The idea for this approach to document decisions was presented a couple of years back at the Software Architect conference in London by Austin Bingham, but it is by no means a new idea.
The principle is very simple, create a means to discuss a decision before they become a fait accompli.
The decision could be an architectural design change, it could be an approach, or even a technique, the crucial point is you create a means for people to provide their input on important decisions and facilitate conversations around them.
We have plenty of reference examples in the wild for this approach, Python Enhancement Proposals or the pretty much canonical example: IETF’s RFCs (adopting one of my favourite RFCs 2119 is not a terrible place to start when writing your ODPs).
Our experience
After hearing Austin talk about this, I was sold on the idea, what is good enough for the IETF was good enough for us.
We tested it on a fairly sizeable project I was involved in, and have since rolled it out across numerous projects, and it has proved pretty successful.
Let’s take a look at how we do things and why we feel it works.
Creating an ODP
First of all, who creates an ODP? Easy, anyone! This isn’t the sole preserve of the elders of the ivory tower, this is about encouraging communication and empowering people to make changes.
We have a rough criteria for when to make an ODP. If something seems ‘big’ enough that it changes how we work in some way, either in terms of architecture, repositories, significant project dependencies, approaches to working and so on, then that is probably ODP worthy. I guess shorthand for this would be ‘would someone new to the team understand this on their own?’ If the answer is yes, then probably don’t create an ODP.
We use git(hub/lab) to store our ODPs, this has several benefits
- Teams are familiar with git as a Version Control System (VCS)
- We can branch for new ODPs
- Pull Requests (PRs) can be used to provide a timeline of changes
- We can use markdown
We have a template that we use to suggest what the overall structure is, we’ve found it to be pretty good, it allows freedom of expression whilst providing some guiding structure, rather than rigid ‘specification’ type documents (there is a time and a place for these but that’s another post for another time).
I recommend you spend a few minutes and have a look at our guidance template.
Hopefully (having had a look at the above link) this gives you an idea of the level we want people to think at, part of the reasoning here is that as well as documenting decisions it provides a framework within which people can develop their skills when it comes to critical thinking around ‘important’ decisions, the freedom of expression and thought offered is less daunting than having to produce formal specifications and we have seen this approach result in broader reasoning about decisions instead of narrow ‘box-ticking’ activities.
Once a draft is created we review it as a group.
Reviewing
We encourage a share early, share often approach to reviewing, perfect is the enemy of, well, reality, time and a lot of other things, so getting better early input from others can help people along.
Initial reviews are usually done by senior team members to make sure things are going in the right direction, and, honestly, to avoid mass bike-shedding or to shortcut the yak-shaving process.
Review comments are appended to the bottom of the ODP rather than PRs so it is easy to see questions or comments.
Once the draft has moved to a point where a wider review would be of benefit it is sent out to everyone.
We set up mailing lists internally for this, so an ‘announce’ list for senior team members and an ‘all’ list for all others.
Publishing
Once the review process is done, everyone has had an opportunity to comment and any changes have been made, BOOM the ODP is live, and you have not only documentation of your decision but a record of the decision making process itself, which, in my opinion is totally sweet.
Why we have found this is a good approach
It encourages the ‘you must think first’ approach. Too often people leap headfirst into implementation. This is massively fun, but it’s also fraught with danger, it is very easy to go a long way down a rabbit hole before realising something that might have been caught with an early review would have saved you a world of pain and you find yourself in the position where you realise that just because you can make an aircraft carrier out of ice doesn’t mean it’s a good idea.
This brings me neatly on to another benefit, it is the equivalent of doing small commits of code to a feature branch, it is demonstrably better in terms of quality when you implement a pull request review policy, the same applies to design decisions. With the right involvement early on, a lot of time and effort can be saved, and valuable experience and context can be brought to the discussion by more senior people.
As well as the opportunity for review and discussion, it’s a really nice framework within which people can learn, as mentioned before, because it isn’t a ‘formal’ specification, the fear of getting it wrong is alleviated somewhat, and because it is collaborative everyone can get involved, either learning new approaches, new context that is really important to the decision, or new ways of thinking.
Documentation is not terrible. I’ve resisted the nod to big ‘A’ Agile so far (for fear of triggering a turbo rant) but too often I encounter the belief from people where they equate Agile = DOCUMENTATION, LOL NO. This is massively wrong. So are formal specs for the sake of it. This is somewhere in between, fitting somewhere along the ‘just enough’ spectrum, and often exceeds expectations.
If this becomes habit, it encourages great behaviour within teams, no longer are you producing documentation for the sake of it, but you are actively helping your fellow team members understand why it is we are doing things (purpose) you are giving people the ability to suggest and make changes (autonomy) and you build up a library of information and demonstrative thinking that others can learn from (mastery). I think maybe this is something has been proven to help people beyond just building ‘stuff’.
Maybe worth a try?
Feel free to give me a shout if you want to have a chat. Rory
