top of page

Write an RFC — Technical Writing for Engineers, Part 5

Shift Quality Editorial
35 minutes ago
7 min read
Technical Writing for Engineers · Part 5

An internal platform team at a large retailer proposes retiring the old authentication library that about thirty services still use. They write a careful RFC, post it in the engineering channel, and open a two-week comment period. Eleven people react with a thumbs-up. Three leave comments, all supportive. At the end of the two weeks, the team announces the decision and a six-month deprecation window.


In month four, the team that runs the in-store tills says the new library doesn't support the offline mode their devices depend on during network outages. They hadn't commented because nobody on that team reads the engineering channel. The deprecation is paused, and the platform team spends a quarter building the feature they would have scoped in week one if they'd known.


The working claim for this part: an RFC is not a vote and not an announcement. It's a structured way to find every objection to a change that affects many people, and to show, in public, how each one was handled. Supportive comments tell you very little. The value is in the objections you go looking for.


Before you start


  • Pick a change you're considering that affects teams other than your own: a shared library, an API, a platform default, a process every team follows.

  • List every team that would have to do something, or would notice something, if the change went ahead. You'll need this in Step 5.

  • Find out whether your organisation has an RFC process and template. If it does, use it and apply the steps below inside it.


Step 1: Choose the RFC for the right kind of decision (5 min)


An RFC, a design doc (Part 1) and an ADR (Part 2) overlap, but they suit different situations. A design doc works out how to build something, usually within one team's ownership. An ADR records a decision after it's made. An RFC is for proposals where the hard part is agreement across many stakeholders, because the change affects how other teams work, what they depend on or what they must do.


The Rust project's RFC process is a well-known public example. Its template asks for a summary, motivation, a guide-level explanation, a reference-level explanation, drawbacks, rationale and alternatives, prior art, unresolved questions and future possibilities. Most internal templates are a subset of that list.


Test you can run: count the teams on your "Before you start" list. If it's only your own team, you probably want a design doc or an ADR. If it's three or more teams who would each have to act, an RFC is the right tool.


Step 2: Write a motivation the affected teams recognise (15 min)


The motivation section has to persuade people who didn't ask for the change and will bear some of its cost. Write it from their side. "The old library is hard for us to maintain" is the platform team's reason. "The old library has had two security patches in the last year that each required every consuming service to redeploy within 48 hours, and it can't support the single sign-on rollout planned for next year" is a reason a consuming team can weigh against their own costs.


Lead the whole document with a short summary: what changes, who is affected, and when. Many readers will stop there, so it must be accurate on its own.


Test you can run: send only the summary and motivation to an engineer on one affected team and ask, "Would you support this, knowing it costs your team work?" Their first objection is a section you haven't written yet.


Step 3: Write the drawbacks honestly (10 min)


The drawbacks section is where readers decide whether to trust the rest. If it's thin, experienced reviewers assume the author either hasn't seen the costs or is hiding them. List the work each affected team will have to do, the risk during migration, and anything that gets worse, even if it's small.


Pair it with alternatives, including doing nothing. "Do nothing" is always an option, and showing its cost honestly is often the strongest argument for the change.


Test you can run: ask the engineer who will most dislike the proposal to read the drawbacks section and add anything missing. Include what they add, credited to them, unless you can show it's wrong.


Step 4: Name the unresolved questions you need answered (5 min)


An unresolved-questions section signals what you want help with. Be specific: "Does any service use the old library's offline token cache?" is a question someone can answer. "Any concerns?" isn't.


This section also protects you. When a problem appears later, it's far better to be able to say "we asked, in section 7" than to discover that nobody thought to ask.


Test you can run: for each unresolved question, write the name of the team most likely to know the answer. Any question without a name is one you'll need to take to someone directly, not leave in the document.


Step 5: Run the comment period to find objections (15 min)


This is the step the retailer in the opening skipped. Posting an RFC in a channel and waiting reaches the people who read that channel. It doesn't reach the team whose devices go offline.


The IETF's guidance on consensus is useful here, even for an internal process. RFC 7282 (Resnick, 2014) describes consensus as the point where everyone is "sufficiently satisfied with the chosen solution, such that they no longer have specific objections to it", and explicitly rejects the idea that counting votes or percentages can determine it: "It's the existence of the unaddressed open issue, not the number of people, which is determinative in judging consensus."


That changes how you run the period. Contact each team on your list directly, by name, with the specific question for them. Track objections, not reactions: keep a list of every objection raised and what happened to it. An objection can be addressed by a change, answered with evidence that it doesn't apply, or explicitly accepted as a cost, with the reason written down.


Test you can run: at the end of the period, check your objection list against your team list. Any team with no entry, neither an objection nor an explicit "no concerns", hasn't been heard from. Go and ask them before you close.


Step 6: Close in public, and record the decision (10 min)


Close the RFC with a written decision: accepted, accepted with changes, or withdrawn. List each objection and how it was handled. Then record the decision as an ADR (Part 2), linked from the RFC, so that the reasoning survives after the discussion threads are forgotten.


A public close matters even when the answer is no. People who raised objections need to see what happened to them; otherwise they learn that commenting is a waste of time and stop doing it.


Test you can run: six weeks after closing, ask one person who objected whether they know what happened to their objection. If they don't, your closing note didn't reach them, and the next RFC will get fewer comments.


Worked example (composite)


A composite scenario, not a real company.


After the paused deprecation, the retailer's platform team rewrote their RFC process around Step 5. The next proposal, changing the default retry policy in the shared HTTP client, affected around forty services.


The author built the team list from the dependency graph rather than from memory, and messaged each team's tech lead directly with one question: "Does any of your traffic rely on retries for non-idempotent calls?" Thirty-four teams answered "no" within a week. Four didn't answer, so the author asked again in their team channels. Two said yes. One of them was the payments team, whose refund calls were retried by the client and would have been sent twice under the new policy in some failure cases.


The RFC changed: the new default excluded non-idempotent methods, and teams could opt in. The closing note listed six objections and what happened to each, including one the team had decided to accept as a cost, with the reason. The ADR linked back to the RFC. Nobody needed to pause anything in month four.


Trade-offs to make deliberately


Choice

You gain

You risk

Open RFC in a channel

Low effort; anyone can comment

The teams that matter never see it

Direct asks to each affected team

Objections surface early

Time spent chasing responses

Fixed comment period

A predictable decision date

Closing before the quiet teams are heard

Track objections, not reactions

A real picture of consensus

More bookkeeping than counting thumbs-up

Public close with an ADR

Trust in the process; durable reasoning

Writing work after the decision feels done


Common failure modes


  • Silence read as agreement. The teams that didn't comment often didn't see it.

  • Counting support. Thumbs-up tell you who likes the idea, not who will be harmed by it.

  • Thin drawbacks. Experienced reviewers stop trusting the rest of the document.

  • Vague questions. "Any concerns?" gets no useful answers.

  • No visible close. Objectors never learn what happened, and stop commenting next time.


Final takeaway


An RFC earns its cost by finding the objections from every team a change will touch, while there's still time to act on them. Write the motivation from their side, be honest about the drawbacks, ask each affected team a specific question directly, track objections rather than reactions, and close with a public decision and an ADR. Your next action: for the next cross-team change you propose, build the affected-team list from your dependency data, and don't close the RFC until every team on it has an entry.


Sources




Continue the Technical Writing for Engineers path



bottom of page