.svg)
DesignDocs.dev
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.
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.
Why Write Design Docs
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.”
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.”
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!”
When to Write a Design Doc
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”
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.”
What Makes a Good Design Doc
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.”
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.”
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.”
