Introduction

Major technology decisions are made using the Request For Comment (RFC) document writing and socializing process. The objectives of utilizing the RFC process to propose changes are to:

• Encourage the right level of rigor for decisions that would be painful to get wrong
• Solicit feedback from stakeholders and impacted groups across the team
• Socialize upcoming changes to help teams anticipate impact
• Record our thinking and rationales as a gift to our future selves

An RFC can cover any kind of change, but should at a minimum cover:

• Major engineering decisions, including
  • Proposed new system architectures and new standards
  • Adoption of new technologies
  • Changes with meaningful security/compliance impact or risk
• Process changes

Process

The process for writing an RFC is straightforward.

1. Create an RFC document from the template (and following the steps there for maintaining the document through every step of the process).
2. Work with your RFC sponsor to make sure you’re including the right information without overdoing it, and making sure you socialize your RFC with all the right people.
3. Once you feel like you have gotten to alignment across your stakeholders and the RFC is 90% finished, present your RFC at the Global Architecture Meeting for review. The intent of this meeting is to get final sign off on the RFC from approvers and final input from other product managers, tech leads and eng managers. Any feedback /changes from this meeting must be reflected in the written RFC which will remain the source of truth.
   1. Once you are ready for feedback, even if you haven’t yet had the chance to present at the global architecture meeting, you should change the status of your document to feedback requested. This will let everyone know that it’s time to read the document and leave their comments.
   2. Additionally, once you have changed your document status, please write a comment in the #tech channel in Slack letting everyone know that it’s time to comment. If you aren’t sure what to write, here is an example that you can use:

Hey everyone, I’ve just finished the initial draft of an RFC called “<TITLE>”. It would be really helpful to get some feedback on this. Feedback is due by <DUE DATE>. Link here: <LINK>

Note: You can also sign up for a spot at an Architecture meeting to get early feedback on a draft idea. However, the meeting will not be used for alignment in this scenario.

Frequently Asked Questions

General

How do I know whether an RFC is required for the thing I’m trying to do?

If you are proposing a new standard or a change in standards, write an RFC. If you are introducing a change in technology stack or a new technology, write an RFC. If you’re unsure, ask an RFC Sponsor.

Who are the RFC Sponsors?

Anyone on the Technology Leadership Team.

Who is allowed to submit an RFC?

Anyone on the Technology team can write and submit an RFC for consideration.

Do I have to present an RFC if I create one?

Sort of. The RFC does need to be presented or discussed at the Global Architecture Meeting. If you aren’t comfortable presenting it, your sponsor or a teammate can help you here. The goal isn’t to make people uncomfortable. But the RFC does need to be presented or discussed in a public-ish forum and the author does need to be present to answer questions in some form.

How do we know who we should be socializing our RFCs with?

At a minimum, they should be seen by the tech leads of teams who will be directly impacted by this work happening. The more foundational and more wide-reaching (i.e. across teams) the impact of the decision, the more people should see it. In general best to share things as widely as possible, but also focus on finding the people who have important expertise and making sure they have the time to review and give feedback.

Do I still have to write a product or engineering spec?

The RFC isn’t a replacement for doing the proper process the SDLC (Software Delivery Life Cycle). The RFC is just to help organize thinking and crowd-source the implementation ideas.

How do I handle potential issues with compliance?

The RFC document doesn’t change the requirement for signoff from the compliance and privacy teams for major architectural changes or feature adjustments. These things still need to go through the proper SDLC processes and get sign off on the Engineering specs or Product specs.

Why does it feel like the RFC process is directed towards Engineers?

The RFC process is directed towards Engineers because it’s similar in concept to the Product Management requirements process. The goal here is to give engineering leaders a conceptually similar footing to the Product process of introducing changes. It provides a standard structure to socialize information to the broader organization. While Product Managers are also allowed to create RFCs if they choose, the process is itself is more geared towards leveling the playing field for change management between Engineering and Product Management. It is common (and often expected) for Product Managers to read the RFCs to better understand the work being requested to help prioritize it and ensure it gets the right attention and roadmap placement if necessary.

Document

How long should an RFC be?

Most RFCs will be 3-5 pages in length. Depending on the complexity of the topic, it can be shorter or longer. Remember, you need people to read and understand what you are writing about. If you make it too long, people won’t want to read it.

What is an appropriate level of detail for an RFC?

The RFC should give us enough information about the context, options, and recommendation to keep a good record of what was decided. It should give confidence that the appropriate amount of rigor was given to the decision.

What are the status options for the RFC?

You can create the status types by type “/status” in the table. The options are: draft IN progress feedback requested accepted rejected . The specific meanings of this are defined in the RFC: Request For Comment Meta document.

Do I have to fill out every section of the document?

No. It is not necessary to fill out every section of the document. The sections in the template are there to provide suggestion and structure. They are also there to help remind you of things. If a section make more sense to be left blank or removed, feel free to do so.

What if I want to add more sections?

It’s your document and you are allowed to add sections to it as you believe is necessary. If you think you need a section that isn’t there to better convey your idea(s), then add that section to your RFC. If you think that a particular section should be a part of every document, then contact one of the RFC sponsors to discuss adding it to the base template.

How do I know when I am done or if I should change the status?

An RFC is never going to be perfect. Make your best effort to cover as many of the concerns as you can think of. You won’t get everything on the first try. But that’s also part of the point. When you feel like you have hit a good point in the process, you can change the status, notify the Tech team in Slack and start receiving feedback.

Engagement

How do I know when it’s time to comment?

When the RFC is in a state where the author is looking for feedback, they will change the status to Feedback requested. When the document has a status of either feedback requested OR in progress, then the author is stating that the document is ready for review and feedback. Typically, the author will also let the larger audience know about the document being ready by mentioning it in Slack in the #tech channel or presenting it at the Architecture Meeting to the Engineering leaders.

How does commenting work?

There are multiple ways to give comments on an RFC when the timing is right. The suggested way is to use the inline comment feature of Confluence. This allows the discussion to take place at the right location and context in the document. Commenters can also add comments to the bottom of the document. The discussions in those threads work as well, just feel a little more disjointed. But they are good for more structural issues.

Discussions can (and do) also happen outside of the Confluence in the real world. It is often up to someone who took part in the conversation to briefly summarize the outcome and how it impacts the content of the document.

When the discussion is completed and the document updated, the author can resolve the comment for tracking purposes.

How do I deal with all the comments?

As the RFC author, you should make sure you engage with every comment. The type of engagement will vary towards the comment. Here are a few examples:

• Grammar Error / Typo: You can either agree or disagree and then resolve the comment.
• Content Missing Suggestion: You can have a discussion about the content section or the content itself and then resolve the comment once the content changes have been made.
• Technical Issue: Discuss offline, Teams, in a meeting, via email, Slack, whatever works. Then leave a short (or long) summary in the comment (inline or at the end of the doc) and make the appropriate modifications to the RFC (if there are any required). Then you can resolve the comment.

What if someone closes my comment without talking to me?

If your comment is closed without a response and your comment/concern isn’t already addressed in the document, you can always reopen the comment thread and ask what happened. Try to assume positive intent. On high-traffic documents, sometimes comments are overlooked or closed by accident.

What if I don’t agree with anything?

Respectfully bring your points of disagreement to the conversation. This is part of the process. It might make more sense to have an initial conversation in meeting or over Teams prior to commenting to ensure that you understand the context correctly. But it is important to share your ideas and concerns in a healthy way to ensure that the best decisions are being made with regards to Technology.