Can RFCs Help You Create More Effective Technical Plans Together?
Ways to establish effective processes for collaborating and sharing knowledge
RFCs can help your team collaborate asynchronously, streamline planning, and create more effective technical plans. Here’s how.
As engineering teams grow, it becomes increasingly important to establish effective processes for collaborating and sharing knowledge. One such process we implement at Brightec is the “Request for Comment” or RFC. This article will explore what an RFC is, what should be included in one, and how it can help solve common problems.
What Is an RFC?
An RFC is a document that outlines a proposed technical design or plan for a piece of work so that other engineers can review and provide feedback. An RFC should be a “living document,” meaning it is expected to change over time as engineers provide their input. The first draft of an RFC is not expected to be complete, and it is ok for the document to evolve as the review process progresses.
Some companies (including Brightec in the past) call these “design docs” or “technical design docs.” More recently, we’ve been using the term “request for comment” because it emphasises at its very heart that the document is a vehicle for efficient asynchronous discussion.
(This is not a new idea. The internet has largely been built on a foundation of RFCs, which have been used since the late 1960s when its predecessor, the ARPANET, was being developed. They were titled and crafted in a relatively informal style with open questions and unresolved issues included within them to encourage discussion and debate.)
What Problem Does an RFC Solve?
One of the primary benefits of an RFC is that it allows asynchronous discussions between engineers. Multiple engineers having input into the document reduces the bottleneck of waiting for consensus from other team members. The author is not expected to wait for a full consensus before starting the work, and the document can be updated as new feedback is received.
Additionally, an RFC provides a framework for an engineer to share their findings and technical designs with a wider team. Providing a clear and structured document can reduce misunderstandings and help everyone stay on the same page.
‘Structured’ does not mean ‘templatised,’ though. We actively avoid having a template for new RFCs at Brightec to maintain that informal style and force the author to think about what their document actually needs to include and highlight. Several years back, we trialed a reasonably lengthy design doc template, which was great as a ‘checklist of things you should have thought about’ but ultimately didn’t encourage the level of focussed design discussion we aspired to. Our more recent RFCs feel far more dynamic and concise.
What Should Be Included in an RFC?
There needs to be a specific structure or set of requirements for a good RFC. However, at Brightec, we’ve found that including the following sections can often be helpful:
Overview
A brief overview of the piece of work and the problem space is a good way to kick off the RFC. If engineers outside of a specific project are expected to review the RFC, then a brief summary of the project as a whole might also be helpful. The purpose of this section is to provide context for the reader and help them understand why the work is necessary.
Scope clarifications
It is essential to outline what is in and out of scope for the work. This helps manage expectations and ensure everyone is on the same page about the work. This section can also cover any assumptions that have been made about the project and how the work will be carried out, including any dependencies or existing systems that need to be considered.
Plan proposal
A step-by-step plan of the ‘chunks’ of work that will be carried out could be included in the RFC. This does not need to be a concrete plan, and it is ok to have multiple iterations or phases of the plan or steps that will require further investigation. It can also be helpful for the plan to include diagrams and visual aids (for example, by using tools like Miro).
Code snippets and ‘proofs of concept’
Code snippets and ‘proofs of concept’ can help engineers understand the proposed approach. A code snippet could be a short piece of pseudocode to convey a specific implementation or an example of how code on other projects has been used. Proof of concepts can be useful in demonstrating how a particular approach will work in practice — they could take the form of a branch that other engineers can checkout, review, and maybe even build and run.
Risks
This section should outline what risks have been raised and how those risks can be mitigated. It is essential to consider the potential negative consequences of the work and have a plan to address them.
Questions
An RFC may also include any open or unanswered questions that can be specifically called out, with an expectation for other engineers to answer as part of their review. These questions can be technical or non-technical and should be included to encourage feedback and ensure that all potential issues and concerns are addressed before the work begins.
Test Plan
Including a test plan can help flag any testing ‘pain points’ early on and ensures that testing and quality assurance are considered right from the start of the work rather than as an afterthought. Aim to outline any bespoke testing methodologies, test criteria, and expected test coverage.
RFC Format
There’s no specific format for an RFC, but it should be easy to review and work on collaboratively. At Brightec, we use several methods and document types. Our favourite is markdown, which can be stored alongside the rest of the code and reviewed within our existing code review process. We also use other tools like Google Docs and Miro for whiteboarding.
Using markdown has several advantages, including using version control tools like git to track changes and collaborate effectively and using the same context and tools as much of our other day-to-day work. It also allows engineers to leave comments and suggestions directly within the document, making it easy to iterate and improve the RFC.
Miro is another great tool for creating RFCs, especially if the work requires visual aids like diagrams or flowcharts. With Miro, you can collaborate in real time, making it easy for multiple engineers to work on the same document simultaneously.
A Better Brightec Process
We have been formally using RFCs since Summer 2022 at Brightec. They have already made much progress, especially as engineers work across projects. RFCs have allowed us to iterate quickly on technical designs and plans and have helped us communicate more effectively as a team.
By following the best practices outlined in this article, you can create effective RFCs that encourage collaboration and improve technical designs and plans. With the right tools and processes in place, RFCs can help your team to work more effectively and efficiently, allowing you to deliver high-quality work in less time.
Originally published at https://www.brightec.co.uk.
