PropertyGuru’s Technical Decision-Making Framework Explained
At PropertyGuru we want to make fast and safe decisions while also valuing lightweight artifacts that can be produced easily.
The goal of putting up a technical decision-making framework is to capture enough information, so we can refer to it later on and get a better picture of the thinking process that led to a particular decision. Of course, looking at Git commits alone makes it very difficult to understand the context, constraints, and pressures that existed at the time of a decision.
How do we Make Effective Technical Decisions?
There are three key levels of decision-making processes we address:
- PG-wide decisions use the Theorem
- Interested Party Reviews (IPRs) should be used across teams, tribes, groups, and lines of business
- Architecture Decision Records (ADRs) are for single-team decisions
Theorem
The Theorem process exists so that decisions that have a significant impact at a larger scale can be made with adequate support, practice, and understanding, just as they would at a team level. With ample collaboration, consultation, and feedback, the Theorem aims to prevent technology sprawl, decrease complexity, and prevent teams from slowing down. The majority of them take weeks to months to complete, and there are few of them.
Theorem requires conversation and a proper understanding of the options. The aim is to get it done properly, so the rule of thumb is to allow time for it to happen, usually around one to four weeks. You’re not expecting people to rock up to the showcase and make a decision or recommendation. The decision itself should be done collaboratively, during the entire process, then properly described in the “Experiments” section.
IPRs
The Interested Parties Review is a RACI-compliant process that is used for all design decisions on projects. The purpose of the review is to more broadly canvass thoughts on solutions, as well as get important stakeholders involved. The vital consideration for this process is that it is not intended as a gatekeeper, or blocking process. It’s designed to enable the conversations required to get good ideas and designs into production, that support all the stakeholders.
IPRs place focus on a few key points around decision-making:
We make decisions all the time and it is important to recognize this and allow time to think and prepare appropriately;
- Decisions cannot occur in isolation given the complex landscape that is PG’s marketplace, product set, technology, and people landscape;
- Documentation must be captured relating to decisions we make to provide the context in the future.
ADRs
It is a simple document that captures a decision, including the context of how the decision was made and the consequences of adopting the decision. This will be more applicable to a single team or project-level decision. Depending on the technical challenges facing the team, these sessions will be scheduled quite often.
Here are the benefits of having ADR in place.
Alignment — As we’ve moved away from monolithic architecture towards microservices or serverless, decision-making has become more and more important in software engineering. With teams having more autonomy, there is a fundamental need for alignment and at the core of alignment sits the need for better communication of decisions being made. ADRs can help with this by keeping the code, team, and architecture aligned by utilizing lightweight decision records.
External Visibility — Having visibility removes duplicative efforts, making code reusable across squads, projects, and reducing the variance of solutions. For example, a team in one area of the business documents the decisions on adopting “React Hooks”. This documented decision can be used as a starting point for other teams.
Onboarding — Future team members are able to read a history of decisions and quickly get up to speed on how and why a decision was made, and its impact.
Ownership Handover — We are an agile company where we aim to learn fast. In this environment, we do not hesitate to implement organizational change to meet the needs of our users as we evolve. When our organization changes, we sometimes have to move ownership of systems from one team to another. This can cause a loss of context/knowledge, triggering a decrease in productivity. The severity of this problem can be reduced by introducing a common way to do ADRs.
