“Change is the only constant in life.”
—Heraclitus
The software we build at FreeAgent is constantly changing and evolving. The requirements of our software can change for a wide variety of reasons, including: scalability concerns, changes to the law or organisational changes. It’s impossible to list all the reasons why your software might have to change, but it’s crucial to acknowledge that it WILL change.
In order to clearly communicate the need for change and to keep track of any decisions made along the way, we have employed a process that works extremely well for larger engineering teams. For reference, our engineering team consists of over 80 talented people, that includes engineers, managers and testers.
Request For Discussion (RFD)
Every significant change needs to be communicated with its internal stakeholders. Whilst smaller changes can usually be decided within the team, larger changes typically require input from other teams as it may affect the area they are responsible for.
Quality work can only be achieved if you have quality time to focus on it. We want our engineers to have this quality time to build exceptional software that our customers love. However, that means they won’t always be available to join the conversation immediately. For that reason we use asynchronous ways of communicating this information. This allows participants to digest the information before responding. We want to avoid snap decisions.
For our purposes, we use Google Docs to write these proposals in a document which we call a Request for Discussion (RFD). Google Docs is great for collaboration. It allows us to review content in our own time and leave comments whenever a section needs clarification, or to provide valuable feedback.
All RFDs that we write follow a predefined structure which enables us to clearly communicate the intention and desired outcome of a proposed change. The outline of the structure is:
- Header – contains the title, a unique ID (e.g. RFD-2019-0098), list of authors, the name of the owner, list of stakeholders, the date and the current state (draft, review, accepted, implemented, abandoned).
- Motivation – this is where we explain the reason why the document exists; what problem are we trying to solve?
- Research – a description of the current state and how possible solutions were evaluated.
- Possible solutions/actions – a list of solutions or actions to consider to solve the problem. Depending on the context more than one may apply.
- Summary – a summary of the entire document and a recommended solution with its consequences.
- Questions – opportunity for readers to leave questions that will be answered by the authors.
- References – a list of links to relevant resources.
- Appendix – collection of diagrams, code snippets or tables to support the document. We extract this into a separate section to preserve the pace of reading.
Here’s an example template:
Once an RFD is ready to be reviewed, we post a message in our internal discussion platform (powered by Discourse). This will send a notification to the engineering team via email and Slack. At this point, we also alert the stakeholders to make them aware that their input is required to make a decision. This is a manual process at the moment but we are aiming to find a solution to automate this step in the future.
Architecture Forum
We found that changes with a wider impact are easier to discuss with an additional in-person conversation. If you have read Ed Catmull’s fantastic book, Creativity Inc., you may be familiar with the concept of the Braintrust. We have taken some inspiration from this concept and used it to help us make large-scale architecture decisions.
We invite several senior or principal engineers with a diverse skill set to these meetings. Every participant is required to read the supporting RFD first, before joining the meeting. This ensures that everyone is on the same page and shares the same context. Furthermore, we don’t need to reiterate information that would take away time from the actual conversation.
These meetings allow all participants and stakeholders to ask questions that couldn’t be answered via comments in the RFD, and delve right into the details with the author. These meetings have a clear goal: make a decision. Ideally, this would mean that we approve or reject an RFD but this is not always possible. If an RFD can’t be approved or rejected at this point, we define clear actions, which need to have an owner, to move the development of this request forward.
Keeping track of decisions
As your architecture and organisation changes, it’s important to keep track of the decisions that have been made over time. The decision should provide enough context to make it clear why it was made, even months later. Perhaps, at the time, there were constraints such as budget limitations or the lack of a piece of technology.
We track these decisions in our RFD Register spreadsheet and they serve as a formal architecture decision record. The state of the decision is also updated in the RFD accordingly. We communicate any changes or decisions via our discourse-powered discussion platform for increased visibility.
It is good practice to record any changes in a lightweight format and in your codebase as well. This will be beneficial for any engineers joining the team and it also keeps your decisions in sync with your changes.
We produce a lot of RFDs! Over 100 have been written in the first 8 months of 2019! This shows the importance of being able to track the state of each decision.
Conclusion
Making architectural decisions is difficult and requires a lot of coordination between your engineers. Below is a list of steps that work very well for us:
- Give people context, i.e. write it down.
- Encourage asynchronous communication to give people the space to think their input through.
- If needed, get everyone in a (virtual) room to ask for advice.
- Keep track of your decisions.
Although our decision making progress works great most of the time, we still struggle in some areas. Naming decision owners in particular is something we would like to introduce, to reduce the time to make a decision. It is also sometimes unclear when a discussion requires an additional conversation at the Architecture Forum.
How does your organisation make and track architectural decisions? Please let us know in the comments.