Doctrine Engineering Principles and Practices
In a previous article, I explained how we managed to formalize where we should spend our sustained engineering efforts in 2021. Part of that exercise involved our coordination group representing the various squads and chapters. In addition to this work, the coordination group also came up with Doctrine Engineering Principles and Practices.
The need for those raised when we realized that sometimes Doctrine core values were interpreted slightly differently by different engineering team members. In particular Doctrine has a very strong value around Releasing Early, Releasing Often and Listening to our Customers. That value when somewhat misinterpreted can lead engineering to build systems as fast as they can (to release early) without sometimes thinking about the ability to release often. Kind of breaking the initial intent. For that reason we wanted to translate Doctrine values in terms of engineering principles in order to make it crystal clear how they apply at engineering level.
If you want to learn more about values, principles and practices in general I encourage you to read this article. But basically values are a set of short beliefs of how an organization should work.
Together with Doctrine vision & mission statements they shape what Doctrine is today and where we want to be. As a reminder Doctrine vision is to have an open justice around the world and for that we aim to connect legal professionals to data, information, news and insights, making law accessible and understandable.
Principles are how we will act, they derive from the values and the vision of the company. Finally practices are actions to be taken in specific situations to follow the principles. They basically translate principles into things you need to apply every day.
Each of the next four sections is describing one of the Doctrine core values and how it was translated into a set of engineering principles.
#CORE1 : Challenge the Status Quo
The Value : To fulfill our mission, we have to challenge the established order. We lead by championing bold ideas, taking intelligent risks and accepting sensible failures. Internally, we constantly change our processes and organization to be more efficient. We respectfully challenge decisions when we disagree, we do not compromise for the sake of social cohesion. All in the spirit of finding the best answers, discovering the truth and making the best decisions.
Nothing that is committed today is necessarily committed forever, and not everything has to be perfect at first. For that reason, when coming up with a technical solution, it is important to propose something we can easily build on and that will let us move forward in all circumstances.
This also means, as an engineer, you have the responsibility to question current choices and implementation.
#CORE2 : Liberty and Responsibility
The Value : Everyday, we invent the future of law. As the saying goes, “with great power comes great responsibility”: we must do the right thing and be socially responsible given the impact we have on our society. Internally, we foster liberty and empowerment. We want owners, who feel a sense of responsibility to do the right thing to help the company. Owners bear the responsibility of their actions. Responsibility also means frugality, to always accomplish more with less.
You are the owner of the change you want to see in the code or in Doctrine processes. This goes along with the CORE1. We encourage engineers to take initiatives to make our infrastructure, architecture and code base better by proposing and pushing forward new ideas. However with liberty comes responsibility and in order for initiatives to not act as reaction forces against the other principles, we understand that adopting a new language, a structuring 3rd party library or a new piece of architecture must not be something done in isolation but as a team. Responsibility is also about taking responsibility for your choices and making sure you support them once done.
#CORE3 : Knowledge is Power
The Value : In the 21st Century, information is a competitive advantage. We provide our customers with access to the relevant data, because they know that Knowledge is Power. Internally, we want everybody to share information broadly and systematically. Employees should always be learning new skills and techniques. Managers have a duty to grow people. When taking decisions, we believe that data beats opinion. If knowledge is so powerful, then we must sometimes protect it. What we know makes us stronger, and confidentiality is the key to flourish and protect ourselves.
Share info broadly and systemically internally and in a public manner. Avoid taking decisions on private Slack channels or offline discussions. When this happens write down your choices and the reasons behind them so it can be shared.
Additionally, effective knowledge sharing that really empowers engineers goes beyond sharing ideas or suggestions of personal practices and for that we should strive for common practices, APIs and data structure that will be a common engineering knowledge for the entire team.
#CORE4 : Release Early, Release Often and Listen to your Customers
The Value : We believe that our only sustainable competitive advantage is customer obsession. We strive to deliver the best customer experience and we put customers at the center of everything the company does. We constantly discover and test new product opportunities. We relentlessly deliver new features and improve the product. We listen to their feedback to reach excellence. Internally, we strive to find the fastest and cheapest way to solve any problem, to validate any hypothesis.
In order to support Doctrine business and objectives we must have a steady delivery pace. However we should not compromise on developer experience, ability to iterate later or Service Level Objectives (SLO) in order to release early. For that we need to find the pragmatic balance between the following Do and Don’t:
Do
Iterate on features: We strive for early delivery and ability to iterate rapidly by releasing often.
Listen to feedback: As we listen to our customers we understand that we should focus the technical effort where it will ultimately have the most long term customer impact.
Don’t
Release buggy and untested feature: We understand that releasing early & often does not mean releasing fast and dirty.
Release weak, inconsistent and/or undocumented code: we know that releasing early & often especially on the long run requires having a solid, consistent, documented and ready to evolve infrastructure, architecture and code base which in itself takes time and effort.
Practices
From those principles we derived practices that I won’t describe in details here, but basically we decided how our principles impact daily practices like doing and reviewing Pull Requests, fulfilling our SLO, or documenting our technologies of choice through a Technology Radar.
I would however like to highlight one of those practices, as it encompasses most of our values: the Request For Comments (RFCs) practice. This is relatively similar to a practice I introduced in previous job called Architecture Document Record (ADR). The idea is that the main technical decisions should go through a RFC document.
The intent of a RFC is first to gather comments from any interested engineer so they can challenge the decision (value: challenge the status quo) and then build a consensus or at the very least a common understanding of the decision (value: liberty & responsibility). The second intent is to document (value: knowledge is power) our decisions such that weeks or months later when we come back on the subject we can precisely know why something was done and we can iterate on them (value: release early, release often, listen to your customers)
Inspired from ADRs Doctrine RFCs contain four sections:
- The context, why do we need to take a technical decision? What has changed?
- The solutions, it is strongly encouraged to foster the discussion to propose alternate solutions to a problem so we can weigh pros and cons
- The decision, what decision do we want to take, and why?
- The consequences, there is no decision without consequences, for example if we choose a different library to replace an existing one we will have code to adapt, if we decide to do X instead of Y, we have some regressions to deal with….
Moving forward we hope that clarifying those principles and practices will among other things help new engineers being more easily on-boarded into the team.
