Teams building products and processes with diverse opinions grow stronger and deliver better products. In order to do that, your team needs to feel empowered to bring forth ideas AND be willing to discuss all ideas openly. Our team has found success building this culture by adopting two processes:
- a decision log written in a tool that supports all team members as authors and commenters
- a once-a-week forum for technical topics to be reviewed and decisions to be closed
About 9-10 months ago, I received some feedback from our team that I, as the team lead, was too prescriptive in our solutions, not allowing our engineers to flex their creative muscles and prohibiting them from learning from experience. It was a sobering moment. As an individual contributor, I excelled under environments where I was given lots of freedom to pick my problems and solutions that had the highest leverage. Here I was as a leader, choosing and selecting exactly what the team did and how they would do it.
The decision log and tech review forum is the first and second step towards building a new culture where our team guides the way instead of the forceful manager. A key aspect of the decision log is that commentary is provided asynchronously which means each decision needs to stand on its own without needing a presentation or walk-through. Allowing for asynchronous commentary is another step that allows for an inclusive team. Team members have busy workloads and schedules. Having an asynchronous feedback format allows for team members to work on their own schedules.
Decision Logs: Get the Whole Team Involved
Many communities from Open Source projects like Rust and the Internet Engineering Task Force have RFC books to allow community members to propose changes and get feedback on those changes. We’ve opted to call our RFC book the “Decision Log” because these can be decisions not necessarily related to our technical products and span the gambit from how we handle new work or production incidents to whether or not we should overhaul a key flow in our architecture.
Why write decision records?
Most engineering teams write decision records to document the context and reasoning for a decision, the why. Michael Nygard’s architecture decision record article does a great job of describing this reason. Our team writes decisions for that reason AND ALSO to encourage a culture of innovation, collaboration and challenging the status quo. Our team wants to be invested in our product and team. The best way I have seen that happen is for whole team to be a part of the roadmap and decision making processes.
When do we write a new record?
Engineering teams make a handle of decisions each day, and we choose to document the decisions that will immediately impact our team or will play a significant role in the future of our product.
Some key categories for decisions records include:
- New standards or development conventions — Ex. “Proposal to adopt new package structure for synchronous APIs”
- Architecture changes such as new components or patterns — “Decision to decommission our custom lead management flow in favor of a Division Level Lead API”
- Process improvements or changes — “Decision on how the PR process will change with the recent split in our team workload”
- Research topics are also documented as decisions. — “How will we integrate with the new ‘Saved Deals API’?”
What is in a decision record?
The most important part of a decision record is recording the context and the alternatives considered. Without a decision record, teams are able to see what was chosen because it will be in the team’s architecture, code or process. They won’t see why you chose it or proposed to even go down that path. Without that context, teams can diverge from the decision and possible re-learn the lesson the team already learned the hard way. Build decision context.
Record Lifecycle
- Decisions are started by engineers or product managers filling out our decision log template which will create a new Github Issue.
- The decision owner will pitch the idea in the next standup or immediately in our team chat channel
- The team will collaborate and give feedback on the proposal “offline”
- Since our decisions span a big breadth of topics, many can be closed out and decided with just asynchronous collaboration
- When decision records get stuck without progress, we’ll use our tech review sessions to get them unstuck and moving towards a conclusion.
Tech Review
The tech world is a big, big place. Ideas are bouncing around inside companies and “out there” in the industry. We use tech review to gather round and hear from engineers on topics ranging from new software patterns we just finished implementing, new decisions we’re considering and new technology we should adopt. Each week is a 50 minute session with an agenda finalized on the day of the meeting. Presentations come from engineers of all levels and the occasional product manager. These sessions are a fun way to learn from each other.
Closing
We’re still learning and growing. One of the things I’m considering is how to get better acceptance and clear understanding on our decision records. We’re considering having decision record sponsors such as tech leads or product managers who will help champion the ideas to their completion. Have an idea or seen success writing RFC books or decision logs? Send me a message at blog@scottpopplewell.me; I’ve love to hear about it!