#
DesignDocs.dev
A curated library of our favorite 1000+ design doc examples and templates from 40+ leading engineering organizations and open source projects
I.
Introduction to DesignDocs.dev
What are design docs?
Design docs are lightweight planning documents written before implementing code to solicit feedback, derive alignment, and create documentation.
A cloud architecture diagram created using Eraser
What about RFCs?
RFCs (reqeust-for-comments) are a type of design docs that emphasize broad solicitation of input. IETF coined the term in the 1960s. Many OSS projects and companies have embraced the term.
II.
Design Doc Library
Browse Library
Sourcegraph
“Our goal is for RFCs to be lightweight, low-process, and effortless to create and use.”
Google Flutter
Company
•
Framework
•
Design Doc
Flutter is an open-source UI software development kit created by Google.
Cockroach
"An RFC is a form of communication aimed at both spreading and gathering knowledge”
IETF
Non-profit
•
Internet Protocol
•
RFC
IETF coined the term RFCs. RFCs started as informal technical notes but now contain technical specifications and organizational notes for the Internet.
Triton
Company
•
Infrastructure
•
RFD
“The philosophy of our RFDs is exactly this: timely rather than polished, with the immediate idea of promoting technical discussion.”
Rust
Most open source projects cite Rust’s RFC process as being the source of inspiration for their respective RFC process.
III.
Why Write Design Docs
III.I
Writing forces clarity of thought. Think through major technical challenges before writing code.
“When we don't take the time to formalize designs we often end up building the wrong thing or supporting a bunch of stuff that we don't want.”
III.II
Derive alignment and break silos. Ensure all stakeholders are confident about the direction.
“We use RFCs to collaborate successfully as an all-remote team... RFCs give us a way to write down ideas and plans so we can communicate, collect thoughtful feedback from others on the team, and make decisions.”
III.III
Create documentation of decision records. Ensure all stakeholders are confident about the direction.
“Creates a record of decision-making and tradeoffs for future readers, so we can revisit "why did we do this?" later. This also contributes to improving our culture of documentation overall!”
iv.
When to Write a Design Doc
iv.I
Will require multiple PRs. Task is large enough to justify upfront time investment.
“When should you make a design document? ... If the change is large/cross-cutting, eg. will be spread over multiple PRs”
iv.II
Impacts work of other engineers and teams. Task is broad enough to require coordination.
“It’s a good idea ... when you want to create awareness across stakeholders. If a change will affect many stakeholders, an RFC should be used to drive clarity and consensus.”
v.
What Makes a Good Design Doc
v.I
Make it easily digestible. Save time and energy for your readers.
“An RFC should be a high-level description which does not require formal correctness. There is utility in conciseness. Do not overspecify the details in the RFC as doing so can bury the reviewer in minutiae.”
v.II
Make it visual. Show don’t tell, a diagram is a worth a thousand words.
“If you can and if it serves the document, be generous with diagrams. A picture is, for most readers, much easier to process than a slab of text.”
v.IiI
Be opinionated. Propose a hypothesis that can be evaluated.
“Your job as the RFC author is to navigate the issue at hand and propose an opinionated solution. Ambiguity creates unproductive discussion and should be eliminated while drafting the RFC.”