Companies Using RFCs or Design Docs and Examples of These

RFCs - requests for comment - or Design Docs are a common tool that engineering teams use to build software faster, by clarifying assumptions and circulating plans earlier. There are some similarities between writing automated tests for your code, and writing RFCs before you start working on a non-trivial project:

Most of these documents are internal to companies. It’s common for engineers moving from one company to the other to bring structures that worked at their previous company.

This article collects some openly available RFC templates and examples, and a list of companies that use such a process. I’d encourage to use these examples for inspiration. Take parts that resonate with you, experiment with them and modify them to your needs.

For a more detailed article on successful planning approaches software engineering teams use, read my longer article: Engineering Planning with RFCs, Design Document and ADRs.

As a note, Product Requirement Documents (PRDs) are commonly run side by side with an engineering design document. This is because if product managers don’t specify what they’d like the team to build, it’s likely the company doesn’t have a writing culture.

See a collection of PRD templates collected by Lenny Rachitsky, the author of Lenny’s Newsletter - the most popular publication for product managers.

Companies that use RFCs or Design Docs

I collected companies where it's common enough to follow and RFC or Design Docs process. Here's a snapshot of some of these places. The article closes with a detailed list, pointing to details to how some of these companies use this approach.

Companies using an RFC or Design Docs process
Companies using an RFC or Design Docs process

Notably missing from this list is Facebook/Meta. While some teams in the company send around 1-pager documents, Facebook is known to have the least emphasis on documentation across all of Big Tech. As I write in the article Inside Facebook's Engineering Culture, Part 2:

“Facebook has less documentation and testing in-place than most tech companies. This approach works for a few reasons: historic ones, engineers having long tenures, Facebook hires some of the best engineers, they built systems to counter the lack of documents and testing. I would not suggest deliberately following this approach, especially not in the age of asynchronous and remote work.”

RFC Examples and Templates

Google

Design Docs overview. Typical document structure:

  • Context and scope
  • Goals and non-goals
  • The actual design
  • System-context diagram
  • APIs
  • Data storage
  • Code and pseudo-code
  • Degree of constraint
  • Alternatives considered
  • Cross-cutting concerns

Uber

RFC process overview (used up to around 2019).

Typical structure for services:

  • List of approvers
  • Abstract (what is the project about?)
  • Architecture changes
  • Service SLAs
  • Service dependencies
  • Load & performance testing
  • Multi data-center concerns
  • Security considerations
  • Testing & rollout
  • Metrics & monitoring
  • Customer support considerations

Typical structure for mobile:

  • Abstract (what is the project about?)
  • UI & UX
  • Architecture changes
  • Network interactions detailed
  • Library dependencies
  • Security concerns
  • Testing & rollout
  • Analytics
  • Customer support considerations
  • Accessibility

Sourcegraph

RFC process overview and list of all public RFCs. An example document: Explicit Repository Permissions Model.

Typical document structure:

  • Summary
  • Background
  • Problem
  • Proposal
  • Definition of success

HashiCorp

RFC process overview. An example document: [RFC] Enable widgets in Product

Typical document structure:

  • Background
  • Proposal
  • Abandoned ideas
  • (Custom sections, for example:)
  • Implementation
  • UX
  • UI

SoundCloud

Details on their RFC process.
Typical structure:

  • Header (authors, to be reviewed by, revisit date, state)
  • Need
  • Approach
  • Benefits
  • Completion or Alternatives

RazorPay

Template document and a collection of RFCs. As an example: spatial system RFC. Typical structure:

  • Summary
  • Motivation
  • Detailed design
  • Drawbacks/constraints
  • Alternatives
  • Adoptions strategy
  • Open questions
  • How do we educate people?
  • References

Monzo

Typical document structure:

  • Why solve now as opposed to later
  • Goals and non-goals
  • Client API and how each platform interacts with it
  • New internal tooling
  • Legal and privacy
  • Risks (must have!)
  • Observability and graceful degradation
  • What we still do not know

Dune Analytics

An overview of why the company uses this approach:

Couchbase

RFC template to propose adding to the API and list of all RFCs. A good example is the SDK for error handling.

Typical structure:

  • Summary
  • Motivation
  • General Design
  • Errors
  • Documentation
  • Language Specifics
  • Questions
  • Changelog
  • Signoff

Incident.io

RFC template. “We use it for things like sales process changes as well, so not just technical. But we don’t mandate it, and early stage speed means that we don’t always write them” - Stephen Whitworth

RiskLedger

RFC template. Typical structure:

  • TL;DR
  • Need
  • Success Criteria
  • Approach
  • Awareness
  • Techical Design
  • Backend
  • Frontend
  • Milestones
  • Out of Scope

Stedi

The below is a section from the article Engineering Planning with RFCs, Design Document and ADRs:

RFCs were introduced early at the company. They’re written as .MD files on GitHub, and comments are made also using GitHub. RFCs are typically used for broad, complex projects, company-wide technical mandates or API changes.

The company has an RFC template people can use as a starting point and diverge from as needed. The template is this:


Status

Draft | Proposed | Published

Type

Experimental | Informational | Best Current Practice | Required

Scope

The scope of work affected by the RFC document.

Notational conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119, RFC8174 when, and only when, they appear in all capitals, as shown here, and without quotes.

Context

A description of the problem space and/or requirements that this RFC is set to address.

Decision

A description of the proposed solution, which sets out the specifications of the implementation of the RFC. Should include specific details on how the solution addresses the requirements as laid out in the Context section.

Consequences

Any consequences that are in play as a result of the decision being put into place.


Decision Records are a more lightweight format that Stedi introduced, shortly after starting to use RFCs. These documents are usually written as Google Docs. The company uses this not just for technical decisions, but for a variety of tasks. For example, they wrote a Decision Record for the introduction of a training platform, and for moving their recruitment process from one vendor to another.

Decision records are used for two key reasons:

  1. To codify a decision that's already been made.
  2. As a forcing function to get alignment on a decision that needs to be made

Here is a template of a decision record the company uses.

From an internal memo at Stedi that explains why they place so much emphasis on thinking before coding, and therefore write before they code (emphasis mine):

“Writing a doc is not a perfunctory gesture, and asking for a doc on something is not a punishment or a mechanism for control. Writing a doc is a way of i) surfacing requirements and assumptions, ii) driving clarity of reasoning stemming from those requirements and assumptions. Without this step, our software has little hope of delivering the results we want over the long term.”

As a final thought, not everyone has to write docs here. Some people just want to execute, and there is plenty of room for that, too – but if you just want to execute, you’ll be executing on the plan, architecture, or implementation described in someone else’s doc. Our domain is too complex and our ambitions too large to build software willy-nilly."

CockdoachDB. The main design document summarizing the database itself. This is a great example of summarizing a complex system with a concise and well-written overview. This design document covers these sections:

  • Overview
  • Architecture
  • Keys
  • Versioned Values
  • Lock-Free Distributed Transactions
  • Logical Map Content
  • Stores and Storage
  • Self Repair
  • Rebalancing
  • Range Metadata
  • Raft - Consistency of Range Replicas
  • Range Leases
  • Splitting / Merging Ranges
  • Node Allocation (via Gossip)
  • Node and Cluster Metrics
  • Zones
  • SQL

Details on companies that use RFCs or Design Docs

I asked for examples on what companies use RFCs. I expected some response, but the number of responses was surprising:

From the thread, and from talking with engineers at companies, these some of the better-known companies all use RFCs or Design Docs within engineering:

  • Airbnb. “We write specs and design docs for both Product and Engineering.” - Manish Maheshwari
  • Affirm
  • Algolia - “we’ve found RFCs to be super valuable” - Praagya Joshi
  • Amazon. Engineering teams do design reviews on architecture with technical docs (e.g. API, components, etc). This is on top of the product specifications - called PR/FAQs/working backwards documents. More details in Inside Amazon’s Engineering Culture. Some orgs follow this process religiously.
  • AutoScout24
  • Asana
  • Atlassian
  • Blue Apron. Also have a weekly architecture lab. Details.
  • Bitrise - also using it for non-technical proposals
  • Booking.com. Details.
  • Brex. Details.
  • BrowserStack - “helps work out all the things that are needed from costs/privacy/compliance as well as trying to figure the best way to implement.”
  • Canonical
  • Caroussel
  • Catawiki - "Not only these add great visibility and enable collaboration at scale but also they can link and help align design & development cycles very well" - Özgen Güngör
  • Cazoo
  • Cisco - at least some teams
  • CockroachDB
  • Coinbase
  • Comcast Cable - using ADRs.
  • Container Solutions
  • Contentful
  • Couchbase
  • Criteo. They are called kick-offs.
  • Curve
  • Daimler
  • Delivery Hero
  • Doctolib
  • DoorDash
  • Dune Analytics - with an example
  • eBay
  • Ecosia (an environment-conscious search engine). Details
  • Elastic
  • Expedia
  • Faire
  • Flexport
  • Glovo. “RFCs for engineering design proposals. We also have ADRs in our code repositories for documenting architectural designs.” - source
  • Gojek. “We should have done this much earlier” - quote from their former SVP Engineering
  • Grab
  • GitHub
  • GitLab. Details on their frontend RFC process.
  • GoodNotes: “We do Implementation Plans before starting any medium-large size project, sharing how engineers plan to tackle it.” - Juanjo Ramos
  • Google
  • Grafana Labs
  • GrubHub
  • HashiCorp
  • Hopin
  • Hudl. “For non-trivial projects and technical decisions impacting multiple teams.” - Juanjo Ramos
  • Indeed
  • Intercom
  • Kiwi.com
  • Klarna. "Recently started, specially for company-wide changes but it’s slowly migrating inside specific areas where we now work with Architectural Decision Records (ADR) for smaller things" - Lucas Santos
  • LinkedIn. "A strong culture of writing RFCs and doing RFC reviews.”
  • MasterCard
  • Mews (hospitality system). Details
  • MongoDB
  • Monzo. Details
  • Mollie
  • Miro
  • N26. Details
  • Netlify. Details.
  • Nobl9 (SLO management)
  • Notion
  • Nubank
  • Oscar Health. “They’re a requirement for any large project”
  • Octopus Deploy. “I find it’s net positive when I look across the different scenarios I’ve looked up docs to better understand rather than booking a meeting.” - Colin Bowern
  • OLX
  • Onfido
  • Pave
  • Peloton. “A design docs culture that has swung back and forth between centralized to decentralized over time.  We've taken up ADRs in the last year that focus on ‘decisions’ with ‘design docs’ usually being longer form, often supplementing an ADR.” - he Head of Core Engineering at Peloton
  • Picnic
  • PlanGrid (acquired by Autodesk)
  • Preply
  • Razorpay
  • Reddit. Details
  • Red Hat
  • SAP. “Had a process for Architecture Concept and Design documents.”
  • Salesforce
  • Shopify
  • Siemens. Details.
  • Spotify. “RFCs and ADRs are at this point pretty deeply embedded part of the culture. Also sometimes used for non-technical changes such as re-orgs.” - Marcus Frodin
  • Square
  • Stripe. Details on their writing culture.
  • Synopsys. “When I was VP of Engineering, we had requirements spec (CAE), project spec (R&D) and sometimes implementation spec (R&D).  All changes after code freeze went through an ECR process.  All had reviews by cross-functional teams ( Marketing, CAE, RnD).” - Steve Meier
  • Skyscanner
  • SoundCloud. Details on their RFC process.
  • Sourcegraph (~200 engineers)
  • Spotify
  • Stedi (~80 engineers, Series B)
  • Stream (chat API, ~60 engineers). Details
  • SumUp
  • Thumbtack
  • TomTom
  • Trainline
  • TrueBill
  • Trustpilot
  • Twitter
  • Uber
  • VanMoof (electric bicycles). “teams choose based on their preference and use case between the RFC template (in Confluence) or the KDD template (in Git engineering handbook)” - Alexander Papageorgiou
  • Virta Health (Series E)
  • VMWare
  • Wayfair
  • Wave (money management)
  • Wise. Using more ADRs. Details.
  • WarnerMesia / HBO / Waner Bros Discovery
  • Zalando. Details
  • Zapier. “Helps in outling scope and surfacing issues before you start working on it.”
  • Zendesk
  • Zillow

Early-stage companies where I’m an investor in:

A few other small enough and early-stage startups which use this approach:

For more examples, see responses in this Twitter thread.

I hope these examples were useful. For a more detailed article on successful planning approaches software engineering teams use, read my longer article: Engineering Planning with RFCs, Design Document and ADRs.


Featured Pragmatic Engineer Jobs

  1. Founding Engineer at Complete. $160-205K + equity. San Francisco.
  2. Senior Backend Engineer, Platform at Jock MKT. $140-200K + equity. Boston or Remote.
  3. Software Engineer at Harver. €55-90K. Netherlands.
  4. Founding Engineer at Zählerfreunde. €70-90K + equity. Munich or Remote (EU).
  5. Senior Frontend Software Engineer at Bound. £70-100K + equity. Remote (EU).
  6. Software Engineer at Bound. £40-65K + equity. Remote (EU).
  7. DevOps Engineer at Teller. London.
  8. Engineering Manager at Element. £90-125K + equity. London.
  9. Engineering Tech Lead at Wise. £95-130K + equity. London.
  10. Senior Full Stack Engineer at Calliper. £60-90K + equity. Remote (EU).
  11. Software Engineer at Keeper Tax. $140-185K + equity. San Francisco
  12. Senior Product Engineer at Causal. $150-250K + equity. Remote (Global).

The above jobs score at least 10/12 on The Pragmatic Engineer Test. Browse more senior engineer and engineering leadership roles with great engineering cultures, or add your own on The Pragmatic Engineer Job board and apply to join The Pragmatic Engineer Talent Collective.

Want to get interesting opportunities from vetted tech companies? Sign up to The Pragmatic Engineer Talent Collective and get sent great opportunities - similar to the ones below without any obligation. You can be public or anonymous, and I’ll be curating the list of companies and people.

Are you hiring senior+ engineers or engineering managers? Apply to join The Pragmatic Engineer Talent Collective to contact world-class senior and above engineers and engineering managers/directors. Get vetted drops twice a month, from software engineers - full-stack, backend, mobile, frontend, data, ML - and managers currently working at Big Tech, high-growth startups, and places with strong engineering cultures. Apply here.