I got promoted because of a 3-page document. Not code. An RFC.
I spent two weeks writing it. Rewrote it four times. It proposed killing a system that three teams had spent eight months building. Everyone approved it in one meeting.
That document moved my career faster than two years of brilliant code. Here's what I learned about writing technical documents that actually get approved.
Why Most Technical Documents Fail
The typical RFC dies in committee because the author makes the same mistake. They explain their solution first.
This is backwards. Your readers need to feel the pain of the problem before they will accept your fix. If they don't agree the problem is worth solving, nothing else in your document matters.
I once reviewed an RFC that started with "We should migrate to Kubernetes." The author spent three pages explaining the migration plan. Zero sentences about why the current system was problematic. The document was rejected not because Kubernetes was wrong, but because nobody felt the urgency.
Compare that to an RFC that opened with: "P95 login latency is 3.2 seconds, causing 23% checkout abandonment. We receive 47 failed login reports daily, generating 12 support tickets weekly at an estimated cost of $2,400 per month. This problem grows linearly with traffic, which is projected to double by Q3."
Now people are listening. Now they want to hear your solution.
The RFC Structure That Works
An RFC is a proposal for significant change. It needs to answer five questions: What is the problem? What do you propose? What alternatives exist? What are the risks? What happens next?
Start with a one-paragraph summary. Decision-makers are busy. Give them the core idea immediately so they can decide whether to keep reading.
Then describe the problem in detail. Quantify everything you can. "Authentication is slow" gets ignored. "P95 latency of 3.2 seconds causing measurable revenue loss" gets attention. Numbers make problems real. Abstractions get forgotten.
The section most developers skip is the most important one: alternatives. If you only present your preferred solution, readers will generate their own alternatives and ask why you didn't consider them. This derails the discussion and makes you look like you didn't think it through.
Present at least three options including the option of doing nothing. Be fair to options you don't prefer. If you strawman the alternatives, readers notice and trust you less. After presenting alternatives, explain why you recommend one over the others. This is where you reveal your reasoning and priorities.
End with clear next steps. "Requesting approval to proceed. If approved, I will create implementation tickets by Friday and begin work in the following sprint." Make it easy for decision-makers to say yes.
ADRs: Love Letters to Future Developers
Every developer has stared at confusing code and asked: "Why the hell did anyone think this was a good idea?"
The answer is usually that it was a good idea given the context at the time. But the context is invisible. The deadline pressure, the team composition, the technical constraints, the business requirements that later changed. All of this evaporates, leaving only the code, which looks inexplicable without the context.
Architecture Decision Records preserve that context. They are short documents that capture what was decided, why it was decided, what alternatives were considered, and what consequences were expected.
A good ADR has four sections. Status indicates whether the decision is proposed, accepted, deprecated, or superseded. Context describes the situation that required a decision. Decision states what was decided in specific, concrete terms. Consequences describes what became easier, what became harder, and what risks were accepted.
Here's an example. Title: Use Redis for Session Caching. Status: Accepted. Context: User sessions stored in PostgreSQL with P95 read latency of 45ms, traffic grew 3x in six months, database CPU at 78% during peak hours. Decision: Implement write-through cache using Redis with 15-minute TTL for session data. Consequences: Expected latency under 5ms, reduced database load by 40%, but added infrastructure complexity and a new failure point.
Write ADRs when decisions are made, not after. Two months later you will have forgotten the alternatives you considered and the reasoning that led to your choice. The ADR becomes rationalization rather than record.
Tech Specs: Contracts Before Code
A tech spec describes how to build something. It defines requirements, describes the approach, identifies edge cases, and provides enough detail for implementation to proceed without constant clarification.
Begin with goals and non-goals. Goals describe what this project will accomplish. Non-goals describe what this project will explicitly not do, even though someone might reasonably expect it. For example: "This project will implement Google OAuth login. This project will not implement Facebook or Apple OAuth, which are planned for Phase 2." Non-goals prevent scope creep during implementation.
Describe the user experience before the technical design. Walk through what users will see and do, step by step. This concrete description reveals edge cases that pure technical design would miss. What happens if the popup is blocked? What if the user denies permission? What if they close the popup without completing the flow?
Be specific about edge cases. Edge cases are where most bugs live. A spec that says "handle errors appropriately" provides no value. A spec that enumerates specific errors and how each should be handled prevents entire categories of bugs.
For database changes, include the actual SQL:
ALTER TABLE users ADD COLUMN google_id VARCHAR(255);
CREATE INDEX idx_users_google_id ON users(google_id);
Include a testing strategy and rollout plan. How will you verify correctness? How will you deploy safely? These sections often reveal gaps in the technical design.
The Politics Nobody Mentions
Technical documents are not purely technical. They exist within organizations that have power dynamics, competing priorities, and limited attention.
The real decision happens before you submit. Share drafts informally with key stakeholders. Ask for their concerns. Incorporate their feedback. By the time the document goes to formal review, the people whose approval you need should already be aligned. The formal review becomes confirmation rather than negotiation.
Surprising people in meetings is a recipe for rejection. Nobody likes being ambushed with complex proposals they haven't had time to consider.
Why This Matters More Than Code
AI generates code in seconds. But try asking AI to write an RFC that convinces five skeptical teams to change their architecture. It can't. These documents require judgment, context, and understanding of human dynamics that no language model possesses.
One well-written RFC can change direction for dozens of people. Good writing scales in a way that good coding never does.
The developers who master technical writing become the developers who shape the direction of their teams and companies. The ones who only write code stay stuck implementing other people's decisions.
Full guide on technical writing with more templates: jsgurujobs.com
Top comments (0)