Stop writing bad documentation… Write RFCs instead.
They’re not just a request for comment, but a request for collaboration and communication.
If you’re working in the tech world, there’s a fairly decent chance that you’ve been tripped up or slowed down by bad documentation.
There’s tons of valid reasons why there might be incomplete, unclear, or outdated documentation for the feature, package, API or even app you’re trying to work with. Yet having this empathy for overworked and understaffed developers unfortunately doesn’t remedy the frustration you have to face. There’s no easy way to make time for writing documentation if time is already a constraint, and so it tends to take a backseat. But if there was a way to have a decent foundation for this neglected task, I’d like to think more of us developers would take it up.
Here’s where the RFC comes in.
An RFC is a way for us to explore and justify your technical decision-making to your current and future colleagues at the same time. A way to provide reasoning and context for future developers without littering your codebase with comments. An all-encompassing document outlining what problem needs to be tackled, what options were considered and exactly how it is going to be solved.
Sounds like you want me to rewrite war and peace every time I want to write some code…
I’ll admit that an ‘all-encompassing document’ sounds great and awful at the same time — how is anyone meant to dedicate the time and energy to reading you waffling on about refactoring your monolith repository for 18 pages front and back? So, while it’s important to provide sufficient context and detail for your readers, it’s also important to preserve the concision and clarity of the document, by ensuring there’s no repetition and, most importantly, making it a group effort!
Transform learning within engineering teams
During my first weeks at Birdie, I was subject to so much new information, I didn’t know what to do with it; while it was fascinating to learn so much, I needed a way to help solidify what I thought I’d learnt.
One of the ways I remedied this for an especially large and involved bit of tech debt was by writing the first RFC within Birdie that painstakingly listed out all the tasks we needed to complete to get the task done. At times, I was even referring to specific files within the codebase, and pointing out very particular assumptions I was making. By having this reviewed by my peers, both them and I were certain we were on the same page, and anything I didn’t quite understand was painfully obvious.
On reflection, it became clear that writing RFCs could be super helpful for any new starter, whether new to software engineering, or new to a team. It’s fairly common knowledge that it’s hard to know if you really understand a concept until you try to explain it to others, and I think RFCs are a prime way to do this.
Transform communication within engineering teams
Even for seasoned developers, RFCs are still a really valuable tool. Onboarding to a new team, and having to learn the entire stack can be daunting, even moving teams within the same company can involve learning a whole new product and stack. Having an encyclopedia of documents explaining all parts of the codebase could be indispensable for saving time and mitigating against gaps in knowledge.
We had a time interval-based parameter we needed to add to one of our entities; originally we had settled on saving a 6 monthly interval in milliseconds. The problem we’d overlooked is the user expectation of a 6-monthly interval. An event recurring every 6 months from the 1st of January would be expected to next occur on the 1st of July, which due to varying month length, is non-trivial to do. This is something we probably wouldn’t have realised until it was too late, had we not had a conversation off the back of an RFC comment that challenged our decision.
What’s the difference between an RFC and ADR?
I’ve seen the use of these two acronyms used interchangeably quite frequently, despite the fact that…
- ADRs are short records of decisions that have already been made.
- RFCs are longer exploratory documents, for getting feedback on any plans and for making decisions. Generally, they’re the precursor for an ADR.
I’m an advocate for both; I believe they both have a place within software engineering.
Having said that, there seems to be a lot of confusion between the two and this can result in the incoherence of a set of documentation and uncertainty — should I be questioning the decision made here? Has the decision already been made? Are you asking for my feedback or just letting me know what you’ll be doing?
Writing an effective RFC
Get your colleagues involved! Don’t make your RFC your little baby- encourage challenges to your approach and any questions or alternative solutions. The size and reach of the project should govern who else needs to give their input — for a small piece of tech debt, there’s no need to get the whole team involved, potentially only those who have dealt with something similar, or who wrote the code originally. Try and set a feedback window, so you’re not getting any doubts right before you’re about to start actually building what you’ve outlined.
Having a peer review process also helps ensure that there’s no missing context — if a reviewer doesn’t understand what they’re reading, chances are another developer looking back after a few months trying to understand the problem space, won’t either.
A faux pas of RFC writing can be a lack of structure in the document. A wall of text with seemingly random titles and headings that once made sense but now merely add to the confusion. Sticking to a template can help mitigate against this.
There’s also the foe of a difficult-to-find RFC. At Birdie, we store our RFCs within a Notion database, and this means we always know where to find them. Having said that, Notion’s search functionality leaves a little bit to be desired, so finding a mention of a specific word or phrase can be super trying. It’d be a good idea to try and add tags or categories to the RFC, maybe outlining the context, the tech used, or the feature in question, in order to make it easier to find later.
The structure of a Birdie RFC
Using a document template can make writing RFCs easier for you and your team. Instead of a blank sheet, being presented with something you can fill in the gaps for, can reduce the time and effort needed. Always keep in mind who the audience is, remember the reader might not always have full context on the problem space, and without this, it’ll be hard for them to give any sort of meaningful feedback.
Title
The title of an RFC should be a precursor to your context. Try to avoid acronyms, unless they’re widely used within the industry and will be correctly interpreted by all engineers, veterans, and newbies. Try and think of what you’d search for when trying to find this RFC in 6 months time.
Context
Akin to the abstract on a research paper, this should be a short overview of what you’re going to address in this document. Outline what the initial problem is, whether it’s a feature, an optimisation, or some technical debt, and what you hope to achieve or resolve following this bit of work. It might also be good to outline what sort of feedback, if any, is needed.
Options
In order for your readers to understand why the final plan of action was chosen, it can be useful to add quick summaries of what other approaches could have been to tackle the problem, what the pros and cons were for those methods and why they inevitably weren’t the way to go.
Plan of Action
The chunky bit. This is a breakdown of the tasks required to complete this bit of work and solve the problem. Whether it’s an overarching plan of the architecture of an app or broken down step by step into tickets, it’s important that you convey the approach in a logical and easy-to-understand format.
By breaking your large piece of work down at this point, not only does writing tickets become easier, but it can also help uncover any potential technical implementation questions, and consequently it can double up as your technical refinement.
Next steps
Out of the scope of this bit of work, what, if anything, are you going to be working on next? By adding this detail, it can help give even better context
Questions
Give your readers the option to add questions they want other reviewers’ opinions on, or add outstanding sources of concerns that you’d like the input of others on before you can begin the work
Appendix
An ideal place to list any references, sources or links out to conversations and other planning resources.
The ideal RFC…
….ensures I am super confident in the work I’m doing, because I know we’ve collaborated with the whole team to come up with the most efficient and effective solution to our problem.
…allows me to be certain that I or anyone else could explain or lead the work, because the whole team have had the opportunity to read, reflect and fully understand the work we’re about to undertake and how we’re going to do it.
…is available to refer back to it in a year’s time when I will be able to fully grasp the context of the problem, and be reminded why we took the actions we did.
Once a clear, concise, yet thorough RFC is complete, the author has received enough feedback and the team should be aligned and comfortable with the approach that has been outlined, and confident that it’s the best solution possible given the time and resources available.
We’re hiring for a variety of roles within engineering. Come check them out here:
