Writing an RFC (Request for Changes) isn’t just about documenting a feature change. It's about storytelling. A good RFC takes readers ie, your team members, on a journey: a clear beginning that explains why they should care, a middle that makes them say “oh, that makes sense,” and an end that compels action. It’s not just a dry, technical exercise; it’s persuasion with a hint of engineering charm.
Whether you’re trying to convince your team to revamp the login system or add a shiny new feature, an RFC is your stage. So, how do you write one that stands out?
Let’s dive into the art of RFC writing.
Start With the Why: Define the Problem
Imagine this: You’re at a team meeting, explaining your big idea, and someone squints at you and says, “But… why do we even need this?”
Your RFC needs to answer that question before it’s even asked. This is the most important part of the document, your problem statement. If this section falls flat, no one’s going to read the rest.
Here’s how to nail it:
Be Specific: Vagueness is the enemy of understanding. Saying “Our system is slow” won’t cut it. Instead, try something like: “Page load times on the checkout page increased from 2 seconds to 5 seconds over the past quarter, leading to a 15% drop in completed transactions.”
Use Data: Numbers don’t just make you sound smart. They tell a story that’s hard to argue with. Look for metrics, user complaints, or customer support logs.
Make It Relatable: Don’t just talk about the problem in abstract terms. Show its real-world impact.
Example:
"Our current session token expiration system has led to a 15% increase in login failures. This frustrates users, as evidenced by a 30% rise in support tickets citing re-login issues. If we don’t address this, user retention is at risk."
At this stage, you’re setting the scene. You’re the storyteller introducing the conflict that needs resolution.
Frame the Scope: Goals and Non-Goals
An RFC without boundaries is like a road trip without a map. Sure, it’s exciting at first, but you’ll probably end up lost and annoyed.
This is where you outline what your proposal will achieve (goals) and what it won’t touch (non-goals). Think of this as setting expectations for your audience.
Why is this important?
It keeps you focused.
It prevents “scope creep” during implementation.
It tells your readers, “Hey, this is what we’re solving and no, we’re not fixing everything under the sun.”
Example:
Goals: Reduce login failures by introducing a rolling token refresh system.
Non-Goals: Overhaul the entire authentication flow or address multi-factor authentication issues.
Propose the Solution Like a Pro
Now for the fun part: solving the problem. This is where your technical brilliance shines, but don’t let that overshadow your ability to communicate clearly.
Here’s how to make your proposed solution pop:
Start Simple: Begin with a high-level summary. Imagine explaining your idea to someone who just walked into the room with no context.
Get Into the Details: Once the reader understands the big picture, dive into the specifics. Show your work. What steps will you take? What systems are involved?
Compare Alternatives: Propose at least two other options you considered and explain why your solution wins. This shows you’ve done your homework and thought critically.
Example:
"We propose implementing a rolling token expiration system, where tokens refresh silently every 15 minutes during active user sessions. This approach balances security and user experience by reducing the need for frequent re-logins."
Make Them Care: The Impact
Solutions are great, but they mean nothing without context. Who benefits? What risks are involved? How will this change affect users, developers, or even the codebase?
This is where you map out the ripple effects of your proposal.
Codebase Impact: What modules or APIs are you changing?
User Impact: How will this improve (or complicate) the user experience?
Team Impact: Will this create extra work for QA, DevOps, or Support?
Example:
"This change will primarily affect the session management module, requiring updates to the token handling logic. QA will need to develop new test cases for token refresh scenarios, while DevOps will monitor error logs post-rollout to ensure stability."
The more you think through these impacts, the more credible your proposal becomes.
Lay Out the Plan Like a Mastermind
Implementation plans are the meat and potatoes of your RFC. They show that you’re not just tossing around ideas, you’ve thought through execution.
Your rollout plan should answer:
How will this be implemented? Break it into phases.
How will success be measured? Define clear KPIs.
What happens if things go wrong? Include a fallback plan.
Example:
1. Phase 1: Test the new token system in a staging environment with internal users.
2. Phase 2: Gradual rollout to 10% of users, monitoring token refresh rates and error logs.
3. Phase 3: Full deployment.
Fallback: Revert to the existing token expiration logic if metrics indicate widespread issues.
Invite Feedback: Open Questions
An RFC isn’t a decree; it’s a conversation starter. List any open questions or concerns you have about the proposal. This shows humility and a willingness to collaborate.
Example:
How will silent token refresh handle network disruptions?
Should we notify users about expired sessions explicitly?
Keep it Moving: Add Timelines
Everyone loves a good timeline. It helps people plan, prioritize, and visualize the road ahead. Include estimates for development, testing, and deployment.
Example:
Development: 2 weeks.
QA Testing: 1 week.
Rollout: 1 week.
Write for Humans
Finally, remember that your audience isn’t just a bunch of machines parsing text. It’s people. Some are deeply technical; others aren’t. Write for all of them.
Avoid jargon unless absolutely necessary.
Use headings, bullet points, and short paragraphs to make the document scannable.
Don’t be afraid to inject a little personality. (A touch of humor never hurts.)
Why Your RFC Matters
An RFC isn’t just a formality, it’s a tool for building alignment, solving problems, and driving innovation. When done right, it inspires confidence, encourages collaboration, and sets the stage for meaningful change.
So, the next time you’re tasked with writing an RFC, don’t just think of it as a boring document. Think of it as your opportunity to tell a compelling story. One that makes people say, “Yes, this is exactly what we need.”
Now go write your RFC like a pro…and enjoy the process!