Software Engineering RFC and Design Doc Examples and Templates
What companies follow an RFC-like process, and what are templates and examples to get inspiration from?
👋 Hi, this is Gergely with a free issue of the Pragmatic Engineer Newsletter. If you’re not a full subscriber yet, you missed 20 Years of Software Engineering with Malte Ubl and the one Twitter rolling out Agile. Subscribe to get this newsletter every week 👇
RFCs - requests for comment - also called 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 this week’s subscriber-only 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.
As a note, this post is too long to fit in an email. Read online for the full article:
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. The format is different, called PR/FAQs/working backwards documents. More details in Inside Amazon’s Engineering Culture. Some orgs follow this process religiously.
AutoScout24
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
Cazoo
Cisco - at least some teams
Coinbase
Comcast Cable - using ADRs.
Container Solutions
Contentful
Couchbase
Crierio. They are called kick-offs.
Curve
Daimler
Delivery Hero
Dune Analytics - with an example
eBay
Ecosia (an environment-conscious search engine). Details
Elastic
Gojek. “We should have done this much earlier” - quote from their former SVP Engineering
Glovo. “RFCs for engineering design proposals. We also have ADRs in our code repositories for documenting architectural designs.” - source
Faire
Flexport
GoodNotes: Hudl. “We do Implementation Plans before starting any medium-large size project, sharing how engineers plan to tackle it.” - Juanjo Ramos
Google
Gradana Labs
GrubHub
HashiCorp
Hudl. “For non-trivial projects and technical decisions impacting multiple teams.” - Juanjo Ramos
Indeed
Interncom
LinkedIn. "A strong culture of writing RFCs and doing RFC reviews.”
Kiwi.com
MasterCard
Mews (hospitality system).
Monzo.
Mollie
N26.
Netfify.
Nobl9 (SLO management)
Nubank
Oscar Health. “They’re a requirement for any large project”
Octuopus 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
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)
Razorpay
Reddit.
SAP. “Had a process for Architecture Concept and Design documents.”
Salesforce
Shopify
Siemens.
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 review by cross functional teams ( Marketing, CAE, RnD).” - Steve Meier
Skyscanner
SourceGraph (~200 engineers)
Spofify
STEDI (~80 engineers, Series C)
Stream (chat API, ~60 engineers). Details
SumUp
Thumbtack
TomTom
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.
WarnerMesia / HBO / Waner Bros Discovery
Zalando.
Zapier. “Helps in outling scope and surfacing issues before you start working on it.”
Early-stage companies where I’m an investor in:
Incident.io (incident management, ~10 engineers).
Invact Metaversity (education, ~5 engineers.
mobile.dev (mobile tooling, ~8 engineers)
For more examples, see responses in this Twitter thread.
RFC Examples and Templates
Google. Design Docs overview. Typical 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
This post is too long to fit in an email. Continue reading online for more examples: