RFCs

Most engineers struggle with putting their thoughts on paper. They fundamentally believe that working code has more value than written words. And to some extent this is true. A product that works can be sold and money can be made. A description of a product can’t. But when working within a team, good communication is the backbone of a successful company. Fortunately, or unfortunately, the best way to describe something is still by putting into paper your thoughts.

I read this piece yesterday from FS:

Writing is the process by which you realize that you do not understand what you are talking about. Importantly, writing is also the process by which you figure it out.

It really gets at the heart of the problem.

Engineers, when presenting their ideas to others, usually go through the process of a RFC (Request for Comments). There’s no established format for an RFC, but I find the following template helpful. If the feature is way too simply, you can get by with just the “Introduction” and the “Technical Implementation”:

  1. Introduction - The introduction serves as the starting point for the endeavour. It should explain what problems it’s trying to address and why they are important, or worth considering. It should present the perspective from both the user and from the business. From the user side it should explain what are the changes (e.g. UX). From the business side, what’s the upside of doing it (e.g. improve MRR). For more complex features it’s worth adding links to designs and user interviews. A good introduction will leave the reader with a good grasp of the problem at hand.
  2. Requirements - If the introduction is well written, the reader is able to deduce the requirements by themselves. This section synthesises the introduction and establishes what the solution needs to deliver. The section should touch both functional and non-functional requirements.
  3. Technical Implementation - The technical implementation can be as long or as short as needed - there’s no rule. But just like any other section, the reader by the end should have a good sense of what will happen. When a PR against this feature is made, there should be no surprises. Any nomenclature should be defined at the top of the section, alongside mentioning any new technology being used. If you are using a term that is unusual, or has a different meaning elsewhere, you should disambiguate it there. Diagrams can be useful, but you shouldn’t use them as a replacement for words - only as support material. Using pseudo-code here is helpful, but you should provide the necessary context before presenting it. A technical implementation with just code snippets is a poor one.
  4. Success Metrics - Ask this question: how do you know if this feature was worth your time? This section should answer that question.
  5. Impact on the existing system - It’s important for the team to understand how the new feature will impact them. This can be in the code, but it’s often also at the setup level. For example, if the new feature requires access to a third party this should mentioned. But there are other considerations, like potential costs of a new technology being used.
  6. Alternatives considered - This is a great section to have, because it forces the author to think about other approaches for the technical solution.

If there’s one thing that you should always keep in mind is the following: don’t waste your readers’ time. If something is unclear, it’s on you as the author.