RFC stands for Request For Comments. It’s a process in which decisions are captured in a document, are being discussed by the team, and serves as a reference point to understand the context of the past decisions, looking from the future.
Having a good RFC template encourages a writer to think about different aspects in advance, before even asking for a review, which can save the time of other team members. For example security, compliance, operations. It also encourages to look into prior work to understand if someone has already tried to solve the same issue.
My favorite RFC template originates from the book The Staff Engineer’s Path by Tanya Reilly. Here you can find my notes from the book.
Here you can also find a Google docs version of it – link.
Metadata
- Status –
EARLY IDEA/OPEN FOR DETAILED REVIEW/SUPERSEDED/BEING IMPLEMENTED/COMPLETED/ON HOLD - Author – who to reach out to with questions and comments
- Created at + Last edited at – these can be also tracked automatically with the right tool
🎯 Goals
What problem are you trying to solve or what opportunity you’re trying to make advantage of?
If the goal suggests a question “ok, but why are you doing that?” – answer that question too.
The goal shouldn’t include implementation details
📘 Background
(this section is optional – feel free to remove it if not relevant)
What information does a reader need to evaluate this design? You could include a glossary here.
🎨 Design
How do you intend to achieve the goal.
Give your audience what they need to know. If you’re writing for potential users or product managers make sure you’re clear about functionality and interfaces. If you depend on systems or components, include how you’ll want to use them
It could be couple of paragraphs or 10 dense pages. Could be narrative or set of bullet points
Example parts this section could include:
- APIs
- pseudocode / code snippts
- architectural diagrams
- data models
- wireframes or screenshots
- steps in a process
- mental models of how components fit together
- organizational charts
- vendor costs
- dependencies on other systems
Remember that wrong is better than vague. Don’t skip the design section because you don’t want people to argue about the details.
Be clear about who or what is doing the action for every single verb. Avoid passive tens e.g. the data will be encrypted.
Don’t be afraid of repeating things. Instead saying “this” or “that” spell out exactly what you’re referring to.
🔒 Security / privacy / compliance
What do you have worth protecting and from whom. Does it plan to collect user data in any way? Does it open new access points to the outside world? How are you going to store secrets?
👀 Alternatives considered / prior work
If you could solve this same problem with spreadsheets would you still want to do it?
If you find yourself omitting this section because you didn’t consider any alternatives, that’s a signal you may not have thought the problem through.
Has anyone else at the company ever tried something similar and why isn’t their solution a good fit?
⚖️ Tradeoffs
(this section is optional – feel free to remove it if not relevant)
What are the disadvantages of your design? What tradeoffs are you making because you think the downsides are worth the benefits?
😱 Risks
(this section is optional – feel free to remove it if not relevant)
What could go wrong? Don’t hide your concerns.
🔗 Dependencies
(this section is optional – feel free to remove it if not relevant)
What are you expecting from other teams? Do you meed to provision infrastructure, need approval or support from security, legal, communication, marketing or other teams?
⚙️ Operations
(this section is optional – feel free to remove it if not relevant)
Who will run the system? How will you monitor it?
