Making technical decisions using RFCs

Teams need to make several important decisions in the software development process, from programming languages, architectures, processes, tools, etc. As the project and team grow, making these decisions becomes more complex and essential. In addition, how can you ensure that the decisions made at the beginning of the project are clear so that new people on the team understand the reasons and contexts that led the team to a particular conclusion?

There are different ways to make and document team decisions, and in this post, I will talk about one of them: the RFCs (Request for Comments).

What is an RFC?

[…] Are relatively informal documents that the author creates before embarking on the coding project. […] It documents the high-level implementation strategy and critical design decisions, emphasizing the trade-offs considered at the time.

Why use it?

allow individual contributors to participate in decisions for systems for which they are responsible
allow domain experts to contribute to decisions even when they are not directly involved in building a specific system
improve risk management of decisions made
include teams in decisions, avoiding the process of design by committee
allows a snapshot of the context for the future
allows decisions to be asynchronous.

How to use it?

We have been using this process on Trybe for over eight months, and we are organizing it as follows:

we created a repository on Github to store the documents
anyone on the team can create a branch, copy the template that we made, write a new RFC in Markdown format and open a Pull Request
team members can make comments and suggestions in the Pull Request, and if the RFC is accepted, we merge it. If the RFC is not accepted, we close the Pull Request without performing the merge.

That way, we have a history of all the discussions held to make a specific decision in the pull requests. And in the main branch of the repository, we have the list of approved RFCs. In the image below, we can see some of the critical decisions we made using this process and the number of discussions we had in each one.

This process has been essential for us to evolve the project as a team and provide context for new people to understand the reasons that led us to make a particular decision.

As I mentioned above, there are other ways to do this process. Do you use another format on your team? Are you using RFCs and have another experience? Share in the comments.