⭐️ Quick tip Tuesday: ⭐️ Writing RFCs for fun and profit

I suck at writing documentation. I suck at writing emails. I suck at writing project specifications. In fact I don’t think writing documentation or project specs in a legacy-ridden, quick-changing, of-dubious-quality codebase is all that useful.

Instead, I prefer to focus on writing RFCs.

RFC stands for “Request for Comment”, and I think of it as a short, formal document that describes a proposed change to the codebase. This can be proposing a new feature, describing a way to refactor a problematic function, a specific new pattern to be implemented, or introducing a new technology.

RFCs are about communication

An RFC is not just a document, it is a living organism. It is meant as a tool of communication.

• for the writer themselves: writing is the best way to clarify your own ideas. If your thinking is not crystal clear, you will have a hard time putting it to paper in an elegant and persuasive way
• for colleagues: this allows team members to be involved and feel ownership. They can point out shortcomings, ask clarifying questions, propose alternatives. New features or patterns won’t come out of the blue.
• for stakeholders: a well-written RFC let’s stakeholders understand why technical changes are being made.

RFCs as a persuasive tool

Think of an RFC as a little propaganda machine. They are effective persuasion tools to make the argument for technical groundwork in an otherwise product-driven development cycle.

• writing it convinces the author that their thinking is thorough and the solution covers all possible cases
• reading it convinces the team members that the solution is sound and that their remarks have been taken into account
• reading it convinces the stakeholders that the work being proposed is meaningful, and that the team is taking ownership and accountability
• reading it helps future readers of the codebase understand why certain decisions where made

RFCs help team cohesion

Because they expose the compromises that are inevitably made when doing technical work, they are also an important tool for team cohesion. If a team member disagrees with the solution chosen, they know that they have been heard and that a piece of writing that records their concerns. It allows them to point out that their point might actually have been more salient than expected when the implementation of the RFC starts to veer from the proposed steps, and corrective action can be taken without much discussion or finger pointing.

Keep it simple and punchy

I follow a few very simple guidelines for my RFCs.

• Use Google Docs. Collaborative editing and comments are key.
• Never more than 2 pages.
• Edit, edit, edit until you can’t edit anymore.
  • Think of writing an RFC as writing code: crystal clear, short and efficient. Good With Words and its accompanying coursera course are great resources.

I use the following structure:

• Metadata - date, author, status, title, tags.
• Overview - two or three sentences that explain the purpose and goal of the RFC.
• Glossary - this makes sure that everybody understands the domain problem and its terminology.
• Proposal - one or two paragraphs explaining the proposed change in detail. Use links to external documents, but keep the proposal self-contained.
• Pros - describe the benefits of the proposed work.
• Cons - describe the downsides. This is important. Not only does it help you think through the problem, but it also communicates that you are aware and have incorporated the feedback of other people.
• Implementation steps - describe concrete implementation steps. This helps you think through the problem and keeps everybody accountable. It also puts a concrete scope on the work.

I keep RFCs in 4 folders:

• Drafts - these are free form RFCs that are not ready to be shared yet
• Under discussion - the RFC has been edited well enough to be shared and start getting feedback.
• Deprecated - these are RFCs that were either not finished, or discarded after discussion. Keep them around, certain topics come up regularly, and you can point back to old discussions. Maybe the circumstances changed and an old RFC can be brought back to life.
• Accepted - the RFC has gotten buy-in and gets moved to the codebase itself as an Architecture Decision Record (a topic for a later post). I still keep the Google Doc around in case a new discussion springs up.

Write many, share a few

Sharing an RFC puts a significant burden on the people involved. Think of it as a complicated PR: a team can only tackle so many at once.

I like to write many RFCs, but only share a few. Writing many helps me clarify my thinking, and I like to “keep a few on the fire”. I often come back to them and revise them as I learn more, circumstances change or my subconscious comes up with new insights.

Do you write RFCs?

What about you? Do you write RFCs? What structure and workflow do you use? Do you have advice about technical writing? Please share your comments below!

Comments

[Manuel Odendahl]

Before I could get my workplace to get onboard with an RFC process, I had to write about 15, and relentlessly try to get people to get involved. It's not an overnight thing, but it is tremendously worth it.

[Ed]

very valuable topic and thanks for sharing your ideas on writing RFC.
I've wrote a bunch of RFCs in former companies and can share something i liked most:

• keep RFC in CVS: meaning prepare RFC as md file, store it with the codebase, initiate discussions in Pull / Merge Requests, in that way you will have engagement, you will always have your RFC with code, you will have real Approvals to merge it (meaning 2 or 3 commenters (or all of them)) are fine with your RFC.
• you can also use Notion for RFC, works fine and fun.
• I would add some more points into structure like: Prior Art, Alternatives