Documenting software is always a challenge, one for which there are numerous tools and kilometers of books written. But with most documentation them you’re still left wondering:
What where they thinking when they created this?
A tweet recently grabbed our attention. It was from @buritica, VP of Eng at Splice, and it was a link to an article entitled 6 lessons I learned while implementing techincal RFCs as a management tool. He outlines managing technical decisions using the RFC process. RFC is short for Request for Comments and is a process where someone writes a memo and sends it out for peer review. It has been adopted for collaboration in both standards bodies (IETF) and large Open Source projects (Ember).
Could it be possible to transfer the mental model you had at the time of decision to those reading it later?
We decided to give this process a try as our way of collaborating on technical decision making at VIBBIO.
How we use RFCs in our daily work
Our development team at VIBBIO is distributed with developers in different cities and countries. Establishing “the process” was a matter of creating a GitHub repository and decided add the RFC template of the Ember project as our template. That was it, we where ready!
Our “RFC process”
# The Process
Initiation -> Pull Request
Collaboration -> Comments / Commits
Conclusion -> Pull Request merged or closed
Here are some ways a RFC can be initiated:
✅ something related to our architecture needs to be changed
✅ someone has a hunch that we should use some new technology
✅ write up conclusion to a discussion
✅ we are doing a new thing and the design of it is not obvious
Once an RFC is created, we issue a Pull Request with the RFC as a markdown file. In the Pull Request we discuss debate, add / remove things. Once we have reached a conlusion of sorts either merge or close the Pull Request.
It is important to note that some RFCs are rejected / closed. This is a good thing and is not a failure of the person initiating the RFC. Changes to documents and closing of Pull Requests with text is much cheaper than changes to code or an architecture.
What has become RFCs❓
Since deciding on using the RFC process, we have six RFCs that have been merged. There are four RFC Pull Requests which have been closed.
Merged RFCs:
✓ Introducing feature toggles
✓ Asset tile overhaul
✓ API URL routing
✓ Audio library integration
✓ Frontend project structure
✓ Continuous deployment process
As you can see from the list, there is a mix between decisions on standards and documentation of choice we make.
♥ Our experiences so far ♥
The RFC process is a good way to document the mental model we had when we made a decision. Being it to choose to use a new technology or how to solve an issue. It has not worked as well for agreeing upon standards and procedures. The reason for this could be that we are still a small company and the need for them is not really there.
Where we’ve seen the RFC process being insufficient is when we do not see a consensus forming. This does not mean the process isn’t working, but there are times where you have to step out of the Pull Requests and have a face-to-face meeting (where face-to-face means using some video conferencing tool).
In closing ✓
Using a RFC process as a means to document the mental model we had at the point of making a decision seems to be working well. However, the real proof of its success is something we won’t see until we need to understand a decision that was made a long time ago, and we haven’t needed that yet.
Photo by: https://www.flickr.com/photos/23536504@N07/3447865249/