• Organise
• Our Code

Can RFCs help you create more effective technical plans together

As engineering teams grow, it becomes increasingly important to establish effective processes for collaborating and sharing knowledge. One such process that we implement for mobile app development at Brightec is the "Request for Comment" or RFC. In this blog, we 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," which means that 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 in use since the late 1960's 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.)

(Photo by Sergey Zolkin on Unsplash)

What problem does an RFC solve?

One of the primary benefits of an RFC is that it allows asynchronous discussions between engineers. With multiple engineers having input into the document, it reduces the bottleneck of waiting for consensus from other members of the team. 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 within which an engineer can share their findings and technical designs with a wider team. By providing a clear and structured document, it can reduce misunderstandings and help everyone stay on the same page.

'Structured' does not mean 'templatised' though. We actually 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 is no specific structure or set of requirements for a good RFC. However, at Brightec, we’ve found that including the following sections can often be really helpful:

Overview

A brief overview of the piece of work and the problem space is a good way to kick off the RFC. If it is expected that engineers outside of a specific project will 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 piece of work. This helps manage expectations and ensure that everyone is on the same page about what the work will entail. 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 to have 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 ‘proof of concepts’

Code snippets and ‘proof of concepts’ 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 in place 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 to flag any testing ‘pain points’ early on, and ensures that testing and quality assurance are considered right from the start of the piece of 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 a number of methods and document types. Our favourite is markdown, that can be stored alongside the rest of the code and can be reviewed within our existing code review process. We also use other tools like Google Docs and Miro for white-boarding.

Using markdown has several advantages, including the ability to use version control tools like git to track changes and collaborate effectively, 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 resulted in a lot of progress, especially as engineers are working across projects. RFCs have allowed us to iterate quickly on technical designs and plans, and they have helped us to communicate more effectively as a team.

By following the best practices outlined in this article, you can create effective RFCs that encourage collaboration and result in better 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.