Imagine a world where technological advancements are not just the result of individual brilliance but shaped by collective wisdom and collaboration. In this world, protocols and procedures are not handed down from on high but crafted through open dialogue and consensus-building among peers.

This vision is a reality with the help of Request For Comments (RFC) documents.

RFCs serve as the cornerstone of innovation, providing a platform for individuals to propose, refine, and standardize ideas that shape the digital landscape.

In this blog, we're digging into the process of creating an RFC document, empowering you to bring this process to your next project.

Knowing when to write an RFC

Before diving into the specifics of creating an RFC document, it's crucial to step back and figure out if an RFC document is even needed.

Let me elaborate.

While RFCs are invaluable tools for proposing and standardizing new ideas, they may not always be necessary. Particularly for work that already has an agreed-upon system or small bugs. In those cases, a simple Slack message or referencing existing standards will do.

That said, RFCs shine in scenarios requiring a net new system with structured documentation and community or team input.

We loved Wasp's visual breakdown:

Defining the purpose and scope

This is pretty straightforward, but after you've determined you need an RFC and before you get to work, take a step back and define the purpose and scope of your project.

Start by identifying the problem or need your proposal aims to address. Consider your audience and stakeholders, understanding their perspectives and requirements. If you're part of a wider team, consider how this project fits into the wider product or team goals.

Setting clear objectives and goals that take into account the wider picture ensures that your RFC document remains focused and actionable.

Research your project

Thorough research and background information are essential for crafting a well-informed RFC document.

Gather relevant data, existing standards, and precedents to inform your proposal. Did another company release a similar project? What do they do right? Does this particular project require a specific set of systems to build? Dig into how those systems work and what the team needs to successfully build it from the ground up. Or is there a way to plug and play certain elements?

Questions like these will help set up your project for success and answer questions before they're even asked.

On a similar note, reviewing related RFCs can provide inspiration and guidance, helping you understand best practices and potential pitfalls.

This is also the time to talk to key stakeholders – teammates who will ultimately give feedback or help build the project. Run your initial ideas by them. This will help you further refine your proposal, shine light on valuable insights, and garner support for your proposal before you've even sent it out.

Structuring your RFC

The bread and butter of this entire process: writing the RFC.

Structuring your RFC document thoughtfully enhances its readability and impact.

Here's what you should include…

• Metadata: List key stakeholders, timelines and important dates, status, etc.
• Title: This should be clear and easily identifiable.
• Abstract: AKA a tl'dr; this should succinctly summarize your proposal.
• Introduction: Here's where you set the context of your proposal.
• Problem statement: This should articulate the issue at hand; why is a proposal even needed in the first place? NOTE: The better and more clear you articulate this problem statement, the easier it will be to write the rest of your RFC.
  1. Start with a quick summary
  2. Give background context
  3. Clearly state the problem
• Proposed solution/recommendation: This is the meat of your RFC. Dig into the proposed solution to your problem and get as detailed as you can. This section and the one above are where the research you completed earlier will come in handy. NOTE: This is a great place to add diagrams and other visual representations.
• Technical details: Are there any special technical considerations to take into account? List that here.
• Implementation plan: Put words into action by detailing your plan of action. Bonus points for suggested timelines in each area.
• Planned impact and benefits: What do we anticipate will occur from building this? And what are the benefits of it?
• Considerations: This is the area to address any other considerations (security, legal, community, etc).
• References: This is the place to add references to the research discussed in the last section.

And overall, use clear, simple language when writing to keep everyone on the same page. Especially if you have stakeholders in different departments.

Relevant examples and diagrams will help bring your audience into the conversation and clearly convey ideas or complex concepts. And it goes without saying, but making sure the flow of your RFC – the use of headings/subheadings – will help organize your content and increase overall readability. Which means fewer questions for you.

Share your work

Now for the moment you've been waiting for: requesting comments.

Share your work with stakeholders and remember to directly ask for feedback. That's why we're here!

From there, actively participate in discussions and revisions based on feedback. Address any concerns or objections raised by reviewers, revising and updating the document as necessary to foster consensus and acceptance.

Create your RFC documents with HackMD

Creating a Request For Comments document is a collaborative process that empowers individuals to join up with others in shaping the growth of their project or company.

And when creating an RFC, it's important to have a trusted platform to collaborate. After all, that's the main point of an RFC – collaboration.

HackMD is a collaborative markdown editor that enables you to collaborate in real time, making it an ideal platform for writing RFC documents. With HackMD, contributors can seamlessly share ideas and iterate on proposals, fostering a culture of inclusivity and innovation.

So if you find yourself itching to document in markdown, but still want to be able to collab directly in your RFC, you know you can lean on HackMD.