👋 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:

Gergely Orosz @GergelyOrosz

Software engineers who write tests for their code - and ask for code reviews on it - often ship more maintainable code. Software engineers who write design docs for their architecture - and ask for reviews on it - often ship more maintainable architecture.

9:55 PM ∙ Jun 12, 2022

---

3,820Likes461Retweets

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:

Read the full article online

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:

Gergely Orosz @GergelyOrosz

Does your current/former company have a culture of writing eng design docs or RFCs? For non-trivial projects, writing down the proposal sending it around to gather feedback beforehand. If so, share the company name in this thread. Gathering examples of places that do this 👇

8:56 AM ∙ Jun 14, 2022

---

738Likes72Retweets

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:

Continue reading online