SoatDev IT Consulting
SoatDev IT Consulting
  • About us
  • Expertise
  • Services
  • How it works
  • Contact Us
  • News
  • June 9, 2023
  • Rss Fetcher

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.)

(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. 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.


Can RFCs Help You Create More Effective Technical Plans Together? was originally published in Better Programming on Medium, where people are continuing the conversation by highlighting and responding to this story.

Previous Post
Next Post

Recent Posts

  • Conheça o jogo Chicken Road em Portugal chickenroadcasino.pt
  • Descoperă jocul Plinko în România plinko-romania.ro
  • Remark raises $16M to build out human-powered expert models for e-commerce
  • Threads launches its own DM inbox, as app moves further away from Instagram
  • Chicken Road – Ein unterhaltsames Spiel aus der Schweiz chickenroadgame.ch

Categories

  • Industry News
  • Programming
  • RSS Fetched Articles
  • Uncategorized

Archives

  • July 2025
  • June 2025
  • May 2025
  • April 2025
  • February 2025
  • January 2025
  • December 2024
  • November 2024
  • October 2024
  • September 2024
  • August 2024
  • July 2024
  • June 2024
  • May 2024
  • April 2024
  • March 2024
  • February 2024
  • January 2024
  • December 2023
  • November 2023
  • October 2023
  • September 2023
  • August 2023
  • July 2023
  • June 2023
  • May 2023
  • April 2023

Tap into the power of Microservices, MVC Architecture, Cloud, Containers, UML, and Scrum methodologies to bolster your project planning, execution, and application development processes.

Solutions

  • IT Consultation
  • Agile Transformation
  • Software Development
  • DevOps & CI/CD

Regions Covered

  • Montreal
  • New York
  • Paris
  • Mauritius
  • Abidjan
  • Dakar

Subscribe to Newsletter

Join our monthly newsletter subscribers to get the latest news and insights.

© Copyright 2023. All Rights Reserved by Soatdev IT Consulting Inc.