Writing documentation is usually not the first thing that comes to your mind when implementing changes or thinking about new features. Sometimes you will even get a few dirty looks. However, there comes a point, usually when your product reaches a certain size and complexity, that you realize the benefits of documenting your thoughts.
Hold up – What’s an RFC
RFC (request for comments) is a document where you should be able to describe your topic/issue/idea which you would like to get comments on – to see whether it is viable or not to be transformed into reality. This document is used as a place where all important information is stored so there is no need for private emails or chats. There you can find parts where you describe the issue/problem, its current state, your proposal, alternative options and also timeline.
Structure
There are plenty of various templates freely available on the internet, notable ones including SquareSpace, TensorFlow and SourceGraph but most bigger companies have their own versions.
We’re going to loosely base our structure on the template provided by the team from reactjs. A typical RFC is composed of a header, basic summary of the problem, glossary, motivation, requirements and goals, proposal and alternative options.
Header
Includes the name of the RFC, author information, date of RFC, status of RFC and a list of reviewers.
Summary
A summary has to be just that. A piece of text that efficiently provides any reader enough information to get the gist of everything your proposal covers and decide if it’s worth it to continue reading.
Think of it as a thesis abstract or a broader TLDR. Imagine you’re an engineer searching through older documents for information and think of everything you might want to see in a summary to conclude that this is the exact document you were looking for.
Generally, it should include a brief explanation of the feature and both a summary of the motivation and the solution (i.e., what you want to do, how you want to do it and why you want to do it).
Avoid too much detail and domain-specific technical terms. Prefer general concepts that any engineer can be expected to understand.
Glossary
Take into account what kind of RFC you’re writing. If it’s something related to business logic implementation or a broader problem, bear in mind that it could be a long-lasting document that will likely be read by newcomers and people lacking proper context or understanding.
Think about your targeted audience and add a list of abbreviations and names used in the document, preferably linked to more documentation.
Motivation
Describe the current state and the existing problems you are trying to solve mentioned in the summary. Highlight not only what does not work but also what works well. Answer these questions:
Why are we doing this?
What is the use case?
What is the outcome?
How urgent is it and what is the impact on the project/organization
Requirements and Scope
Write down a list of all requirements that you are trying to accomplish. Double-check them with your product team so that they aren’t skewed by the solution you had in mind. Discovering design flaws late in the development process can be very expensive (and frustrating).
Include goals for other teams that might be part of the scope of proposed changes.
Proposal
This is the bulk of your RFC. Putting your thoughts into words can be a tedious process but it helps to clarify your ideas. Explain the proposed changes in enough detail so that somebody familiar with the situation can understand, and somebody familiar with the implementation can implement. Keep in mind your targeted audience so that they can comprehend this and assess impact. This should get into specifics and corner-cases, and include examples of how the feature is used.
Still not convinced?
Let’s forget about other people for a minute here and focus on yourself. Remember when you go back to that piece of code you wrote a year ago that had oddly specific requirements and it takes you a while to vaguely remember the reasons behind them. Now fast forward 2-3 years ahead and someone asks you that dreaded question:
Hey, I see you last touched this code, can you explain the reason behind it?
and your brain just freezes. You think to yourself, “I can ping that PM that wanted that” but then you remember he left the company a year ago and nobody knows the reasons behind that code except you.
RFCs are made to avoid situations like these and ease life for you and your future colleagues.
Wrapping up
Think of writing documentation as writing code, just on a higher level. Design documents can be highly beneficial and are a wonderful tool to have in your bag.
They force you to structure your thoughts in ways that make your ideas more clear. They allow for early reviewing of your proposed implementation to avoid discovering late-stage design flaws. But most importantly, by defining a process for decision-making, you can rest at ease knowing you don’t have to memorize reasons for every weird code snippet or business decision.
