Imagine youâve been tasked to implement a crucial new feature in the product youâre working on. Thatâs the opportunity youâve been waiting for - everybody will see what a 10x developer you are! You open a list of the coolest new libraries and design patterns youâve wanted to try out and get right into it, full âbasementâ mode. One week later, you victoriously emerge and present your perfect pull request!
But then, the senior dev in a team immediately rejects it - âToo complex, you should have simply used library X and reused Y.â. What!? Obviously, they donât get how genius your solution is, and soon, youâre looking at 100 comments on your PR and days of refactoring to follow.
If only there were a way to know about X and Y before you implemented everything. Well, it is, and itâs called RFC!
Weâll learn about it on the example of RFC about implementing authentication in Wasp. Wasp is a full-stack framework built on top of React, Node.js, and Prisma that offers a ton of features out of the box and is the fastest way to build and deploy your app. It also comes with a free GPT-powered codebase generator, MAGE, that has been used to create over 30,000 applications.
Letâs dive in!
Support us! đâïž
If you find this post helpful, consider giving us a star on Github! Everything we do at Wasp is open source, and your support helps us make web development easier and motivates us to write more articles like this one.
âïž Thanks For Your Support đ
So, what is an RFC?
RFC stands for Request For Comments, and simply means âa document proposing a codebase change to solve a specific problem.â. Its main purpose is to find the best way to solve a problem before the implementation starts. RFCs were first adopted by the open-source community, but today, they are used in almost any type of developer organization.
There are other names for this type of document you might encounter in the industry, like TDD (Technical Design Document) or SDD (Software Design Document). Some people argue over the distinction between them, but we wonât.
Fun fact: RFCs were invented by IETF (Internet Engineering Task Force), the engineering organization behind some of the most important internet standards and protocols we use today! Not too shabby, right?
When should I write RFC, and when can I skip it?
So, why bother writing about what you will eventually code, instead of saving time and simply doing it? If youâre dealing with a bug or a relatively simple feature, where itâs very clear what you must do and doesnât affect project structure, then thereâs no need for an RFC - fire up that IDE and get cracking!
But, if you are introducing a completely new concept (e.g., introducing a role-based permission system) or altering the projectâs architecture (e.g., adding support for running background jobs), then you might want to take a step back before typing git checkout -b my-new-feature and diving into that sweet coding zone.
All the above being said, sometimes it's not easy to figure out if you should write that RFC or not. Maybe itâs a more prominent feature, but youâve done something similar before, and youâve already mapped everything out in your head and pretty much have no questions. To help with that, hereâs a simple heuristic I like to use: Is there more than one obvious way to implement this feature? Is there a new library/service we have to pick? If the answer to both of these is âNo", you probably donât need an RFC. Otherwise, thereâs a discussion to be had, and RFC is the way to do it.
Whatâs in it for me?
Weâve established how to decide when to write an RFC, but here is also why you should do it:
- You will organize your thoughts and get clarity. If youâve decided to write an RFC, that means youâre dealing with a non-trivial, open-ended problem. Writing things down will help distill your thoughts and have an objective look at them.
- You will learn more than if you just jumped into coding. You will give yourself space to explore different approaches and oftentimes discover something you havenât even thought of initially.
- You will crowdsource your teamâs knowledge. By asking your team for feedback (hence Request For Comments), you will get a complete picture of the problem youâre solving and fill in any remaining gaps.
- You will advance your teamâs understanding of the codebase. By collaborating on your RFC, everybody on the team will understand what youâre doing and how you eventually did it. That means next time somebody has to touch that part of the code, they will need to ask you much less questions (=== more uninterrupted coding time!).
- PR reviews will go much smoother. Remember that situation from the beginning of this article, when your PR got rejected as "too complex"? Thatâs because the reviewer is missing the context, and you made a sizeable change without a previous buy-in from the rest of the team. By writing an RFC first, youâll never encounter this type of situation again.
- Your documentation is already 50% done! To be clear, RFC is not the final documentation, and you cannot simply point to it, but you can likely reuse a lot - images, diagrams, paragraphs, etc.
Wow, this sounds so good that I want to come up with a new feature right now just so I can write an RFC for it! Joke aside, going through with the RFC first makes the coding part much more enjoyable - you know exactly what you need to do, and you donât need to question your approach and how it will be received once you create that PR.
Ok, ok, Iâm sold! So, how do I go about writing one?
Glad you asked! Many different formats are being used, more or less formal, but I prefer to keep it simple. RFCs that we write at Wasp donât follow a strict format, but there are some common parts:
- Metadata - Title, date, reviewers, etcâŠ
- Problem/Goal - what are you going to solve
- Proposed solution (or more of them)
- Implementation overview
- Remarks / open questions
Thatâs pretty much the gist of it! Each of these can be further broken down and refined, but this is the basic outline you can start with.
Letâs now go over each of these and see what they look like in practice, on our Authentication in Wasp example.
Metadata â
This one is pretty self-explanatory - you will probably want to track some basic info about your RFCs - status, date of creation, etc.
Some templates also explicitly list the reviewers and the status of their âapprovalâ of the RFC - we donât have it since weâre a small team where communication happens fast, but it can be handy for larger teams where not everybody knows everybody, and you want to have a bit more of a process in place (e.g., when mentoring junior developers).
The problem đ€
This is where things get interesting. The better you define the problem or the goal/feature you need to implement, and why you need to do it, the easier all the following steps will be. So this is something worth investing in even before you start writing your RFC - make sure you talk to all the involved parties (e.g., product owner, other developers, and even users) to refine your understanding of the issue youâre about to tackle.
By doing this, you will also very likely get first hints and pointers on the possible solutions, and develop a rough sense of the problem space youâre in.
Here are a few tips from the example above:
- Start with a high-level summary - that way, readers can quickly decide if this is relevant to them or not and whether they should keep reading.
- Provide some context - Explain a bit about the current state of the world, as it is right now. This can be a single sentence or a whole chapter, depending on the intended audience.
- Clearly state the problem/goal - explain why there is a problem and connect it with the userâs/companyâs pain, so that motivation is clear.
- Provide extra details if possible - diagrams, code examples, ⊠â anything that can help the reader get faster to that âahaâ moment. Extra points for using collapsible sections, so the central part of the RFC remains of digestible length.
If you did all this, youâre already well on your way to the excellent RFC! Since defining the problem well is essential, donât be afraid to add more to it and break things down further.
Non-goals đ
This is the sub-section of the "Problem" that can sometimes be super valuable. Writing what we don't want or will not be doing in this codebase change can help set the expectations and better define its scope.
For example, if we are working on adding a role-based authentication system to our app, people might assume that we will also build some sort of an admin panel for it to manage users and add/remove roles. By explicitly stating it won't be done (and briefly explaining why - not needed, it would take too long, ...), reviewers will get a better understanding of what your goal is and you will skip unnecessary discussion.
Solution & Implementation đ ïž
Once we know what we want to do, we have to figure out the best way of doing it! You might have already hinted at the possible solution in the Problem section, but now is the moment to dive deeper - research different approaches, evaluate their pros and cons, and sketch how they could fit into the existing system.
This section is probably the most free-form of all - since it highly depends on the nature of what you are doing, it doesnât make sense to impose many restrictions here. You may want to stay at the higher level of, e.g., system architecture, or you may need to dive deep into the code and start writing parts of the code you will need. Due to that, I donât have an exact format for you to follow, but rather a set of guidelines:
Write pseudocode
The purpose of RFC is to convey ideas and principles, not production-grade code that compiles and covers all the edge cases. Feel free to invent/imagine/sketch whatever you need (e.g., imagine you already have a function that sends an email and just use it, even if you donât), and donât encumber yourself or the reader with the implementation details (unless thatâs exactly what the RFC is about).
Itâs better to start at the higher level, and then go deeper when you realize you need it or if one of the reviewers suggests it.
Find out how are others doing it
How you find this out may differ depending on the type of product youâre developing, but there is almost always a way to do it. If youâre developing an open-source tool like Wasp you can simply check out other popular solutions (that are also open-source) and learn how they did it. If youâre working on a SaaS and need to figure out whether to use cookies or JWTs for the authentication, you likely have some friends who have done it before, and you can ask them. Lastly, simply Google/GPT it.
Why is this so helpful? The reason is that it gives you (and the reviewers) confidence in your solution. If somebody else did it successfully this way, it might be a promising direction. It also might help you discover approaches you havenât thought of before, or serve as a basis on top of which you can build. Of course, never take anything for granted and take into account the specific needs of your situation, but definitely make use of the knowledge and expertise of others.
Leave things unfinished & keep it dirty
The main point of RFC is the âCâ part, so collaboration (yes, I know it actually stands for "comments"). Itâs not a test where you have to get the perfect score and have no questions asked - if that happens, you probably shouldnât have written the RFC in the first place.
Solving a problem is team effort, and youâre just the person taking the first stab at it and pushing things forward. Your task is to lay as much groundwork as you reasonably can (refine the problem, explore multiple approaches to solving it, identify new subproblems that came to light) so the reviewers can quickly grasp the status and provide efficient feedback, directed where itâs needed the most.
The main job of your RFC is to identify the most important problems and direct the reviewerâs attention to them, not solving them.
The RFC youâre writing should be looked at as a discussion area and a work-in-progress, not a piece of art that has to be perfected before itâs displayed in front of the audience.
Remarks & open questions đŻ
In this final section of the document, you can summarise the main thoughts and highlight the biggest open questions. After going through everything, it can be helpful for the reader to be reminded of where his attention can be most valuable.
Now I know when and how to write an RFC! Do you have any templates I could use as a starting point?
Of course! As mentioned, our format is extremely lightweight, but feel free to take a look at the RFC we used as an example to get inspired. Your company could also already have a ready template they recommend.
Here are a few you can use and/or adapt to your needs:
- Squarespace RFC template
- Do you have a template you'd recommend? I'm happy to list it here!
What tool should I use to write my RFCs? There are so many choices!
The exact tool youâre using is probably the least important part of RFC-ing, but it still matters since it sets the workflow around it. If your company has already selected a tool, then of course stick with that. If not, here are the most common choices Iâve come across, along with quick comments:
- Google Docs - the classic choice. Super easy to comment on any part of the doc, which is the most important feature.
- Notion - also great for collaboration, plus offers some markdown components such as collapsibles and tables, which can make your RFC more readable.
- Github issues / PRs - this is sometimes used, especially for OSS projects. The drawback is that it is harder to comment on the specific part of the document (you can only comment on the whole line), plus inserting diagrams is also quite clunky. The pro is that everything (code and RFCs) stays on the same platform
We currently use Notion, but any of the above can be a good choice.
Summary
Just as it is the best practice to write a summary at the end of your RFC, we will do the same here! This article came out longer than I expected, but there were so many things to mention - I hope you'll find it useful!
Finally, being able to clearly express your thoughts, formulate the problem, and objectively analyze the possible solutions, with feedback from the team, is what will help you develop the right thing, which is the ultimate productivity hack.
This is how you become a truly 10x engineer. Thank you for reading, and until the next time!
Top comments (35)
Another reason to write an RFC is you know there is a teammate that knows a lot about the part of the codebase you are about to work on, and you could use that knowledge -> RFC is then a good way to have an organized communication about it, they can see your plan, enrich it with their knowledge, and you know you are not missing anything out!
Agreed, RFC is a great way to have a structured discussion about a feature/topic.
I guess the biggest trickery is in defining our needs properly from the get-go, then it gets much easier to figure out whether the RFC is worthwhile. :)
Hah yes, that's always the case, figuring out what you actually want or need! :) Any tips from your experience you'd share?
This is a good one - I never heard of RFC before!
Glad you liked it and learned something new. RFCs are a really helpful tool for planning bigger features.
Nice guide to RFCs, love that you included tools at the end!
Thanks a lot and glad you found it useful!
glad it helped! :)
Great learnings, thanks!
Thank you for reading and hope you found it useful!
nice article!
Thanks Kevin!
Enjoyed this piece! Also, loved the diagram :)
Thanks Petar! Yeah, it's a bit simplified so just a heuristic but I thought it might be a good starting point :)
Nice!! I learned a lot here. Thanks for writing up!
Thanks! I hope you find it as useful as we do :)
Nice post. learned a lot from this!
RFCs >> dealing with 20 comments on the PR
Great post!! We also follow a similar RFC process at Flipt.
QQ: Do you make all your RFCs public at Wasp?
We actually make a lot of them public - it's super helpful when sharing RFCs with the community (e.g. ours is on Discord: discord.gg/rzdnErX), we get plenty of good ideas, and it also helps validate the direction faster.
The only reason why not all of them are public is that by default, they are private in Notion, so if it's a smaller RFC, it might already get merged before we open it up. But there is absolutely no reason not to have it all public!
Btw Flipt looks amazing, and I love that it is open-source, might be a great fit to go with Wasp :)
I thought RFCs must be a white paper with boring long text :D
haha :D Yellow is also fine! :)
Amazing. I'll definitely use this one in the future
Thanks a lot Tin! Really glad you found this valuable :)
Please stop perpetuating the myth of the 10x developer. This problematic idea promotes burnout and worsens imposter syndrome, while encouraging managers to push their people to work harder for less pay and fewer benefits.
The 10x developer myth is objectively harmful.
Hey Mike, I appreciate the comment! But did you read the article, especially the Summary? My main point is actually that being a 10x developer doesn't mean coding more or faster, but rather taking more time to plan and collaborate with your colleagues.
Another thing is whether we should stop using the term "10x developer" altogether, is that what you had in mind? I personally don't think it will go away, and that it's not necessarily inherently wrong, but I believe we should all work together on improving its meaning. That could actually be a really interesting topic to cover.
Thanks again for giving it a look!
I agree. The 10x developer is one that is more like "Sharpen the axe and spend 10% of the time to chop down the tree." You get more done if you are planning and execute the right thing, than not planning and execute many wrong things first. Or you may still execute the wrong thing, but you are likely to at least be 10x closer to the right thing that much sooner.
Thanks Victor, that is what I had in mind!
Just like all other terms which cause harm by creating toxic fictions, the use of this term should indeed be discontinued.
There are a variety of terms which cause harm but are nonetheless unlikely to perish from our collective vocabulary, but this does not excuse their continued willful use.
Thanks for the clarification, I see your point now. I agree there is that "myth" of a 10x engineer, when it is in reality just a person doing their job well, which is what we should all strive for by default. I don't think other professions use this term, e.g. "10x teacher" or "10x lawyer".