Writing Clear RFCs (Request for Comments)

In companies like Uber, Airbnb, and Meta, major technical changes start with an RFC. It's the "Source of Truth" for why a decision was made.

The RFC Structure

1. Summary: A high-level overview of the proposal.
2. Motivation: Why are we doing this? What problem are we solving?
3. Goals & Non-Goals: What is in scope and what is out of scope?
4. Proposed Design: The technical details (Architecture, API changes, Data models).
5. Drawbacks: What are the negatives or risks?
6. Alternatives: What other options did you consider and why did you reject them?

Using RFC 2119 Keywords

Technical writers use specific words to avoid ambiguity:

• MUST: Absolute requirement. ("The API must return a 404 if the user is not found.")
• SHOULD: Strongly recommended but not mandatory. ("Clients should cache the response for 5 minutes.")
• MAY: Truly optional. ("The response may include a 'metadata' field.")

Writing Style: Objective & Precise

Avoid "I think" or "I feel." Use data and logic.

• Subjective: "I think the current system is slow and bad."
• Objective: "The current system has a p99 latency of 500ms, which exceeds our 200ms target."

Alex's Tip: The most important section of an RFC is often the "Alternatives Considered." It proves to your peers that you didn't just pick the first idea that came to mind.

Plain words over complex synonyms

| Complex (avoid) | Plain (prefer) | | -------------------- | -------------- | | utilize | use | | facilitate | help | | commence | start | | in order to | to | | due to the fact that | because | | terminate | end |

Plain words are clearer. Save complex vocabulary for when it adds precision.

Define jargon on first use

If you must use technical terms, define them on first use:

• We use ARR (Annual Recurring Revenue) as our primary growth metric.

After the definition, you may use the short form (ARR). Never assume the reader knows every term.

Structure with headings

Break long documents into sections with clear headings. Readers scan technical docs; they rarely read every word. Headings let them jump to what they need.

• Use descriptive headings (How to authenticate, not Section 2).
• Keep sections short.
• Use lists for steps and options.

Common mistakes

1. Long, nested sentences. Break them into short ones.
2. Passive voice everywhere. It hides who did what.
3. Undefined jargon. It excludes readers who do not know the term.

Practice

Rewrite this unclear sentence in clear technical English:

The utilization of the aforementioned methodology resulted in the successful implementation of the deliverable by the team.

A clear version:

The team used the new method and shipped the feature.

In the next lesson, you will learn to write a Product Requirement Document (PRD).