Technical Writing for Engineers: How READMEs, Design Docs, and RFCs Accelerate Your Career
Technical Writing for Engineers: How READMEs, Design Docs, and RFCs Accelerate Your Career
The engineers who get promoted to staff aren't always the ones who write the best code. They're the ones whose thinking is visible at scale.
Here's a pattern that plays out quietly at every company above 50 engineers: two senior engineers have roughly equivalent technical skills. One writes design docs for every major architectural decision, keeps their service READMEs accurate, and authors the occasional RFC when they're proposing something that crosses team boundaries. The other ships excellent code that nobody documents.
In 18 months, one of them gets promoted to staff. The other files a frustrated ticket wondering why their "impact wasn't recognized."
The difference isn't ability. It's evidence.
Why Writing Is a Staff-Level Skill (Not a Nice-to-Have)
Most engineering career ladders are vague about writing until you hit senior+. Then suddenly every promotion packet, every staff job description, every performance review rubric mentions it: "influences beyond their immediate team," "shapes technical direction," "communicates across stakeholders."
That's all writing. You can't do any of those things with pull requests alone.
Gergely Orosz, author of The Pragmatic Engineer newsletter, has documented how companies like Google, Facebook, Amazon, and Stripe all developed RFC or design doc processes independently and for the same reason: beyond a certain team size, code is not the primary communication medium for technical decisions. Documents are.
The staff engineer archetypes described on staffeng.com — Tech Lead, Architect, Solver, Right Hand — all share a common thread: they operate at a scope that exceeds any individual codebase. At that scope, writing isn't supplemental. It is the work.
As one Amazon principal engineer put it in a widely-shared Quora thread: "The 6-pager isn't a tax on getting work done. It is how work gets done at scale."
The Four Documents That Move Your Career
Not all technical writing is equal. These four artifacts are the highest-leverage documents an engineer can produce, roughly ordered from most frequent to most strategic.
1. The README (Your Service's First Impression)
The README is the document every new team member, every on-call engineer at 2am, and every staff engineer evaluating a cross-team dependency will read first. Most READMEs are an afterthought — outdated setup instructions, a TODO: fill this in from two years ago, and a list of environment variables that no longer exists.
A good README answers five questions:
- What does this service do? (One sentence. Not what it was designed to do — what it does right now.)
- Who owns it? (Runbook link, on-call rotation, Slack channel — whatever will get someone help in 10 minutes.)
- How do I run it locally? (Steps that actually work. With the version numbers pinned.)
- How does it fit into the larger system? (A diagram, a list of upstream/downstream dependencies, a link to the architecture doc.)
- What's the current state? (Known issues, active migrations, things that will break you if you don't know them.)
The career signal here isn't that you wrote a README — it's that you treated your service as a product for other engineers, not just code you happened to maintain. That's a staff-level instinct.
Practical note: GitHub's recent analysis of open-source project health consistently shows that repositories with complete READMEs get significantly more contributions and adoption. The same dynamic applies internally: a well-documented service attracts collaborators and gets referenced in more design docs — which builds your visibility organically.
2. The Architecture Decision Record (ADR)
An ADR is a short document — typically 1–2 pages — that records a specific technical decision: what was decided, why it was decided, and what alternatives were rejected.
They're cheap to write (30–60 minutes per decision), and they compound over time. An ADR written today answering "why are we using Postgres instead of a document store for user profiles?" prevents that conversation from being relitigated 12 times over the next three years. When the team is twice as big and the original decision-makers have moved on, the ADR is the institutional memory.
For your career, ADRs serve a specific function: they are timestamped evidence of your technical judgment. When you're making the case for a promotion, you can point to a series of ADRs as concrete artifacts that show what you were thinking, what tradeoffs you evaluated, and what you decided. That's dramatically more compelling than "I led the auth refactor" with no supporting documentation.
Michael Nygard's original ADR format is still the most useful: Status, Context, Decision, Consequences. Four sections. Done.
3. The Design Doc
A design doc (called a Technical Design Doc, TDD, or "one-pager" at different companies) is written before implementation. It answers: what problem are we solving, what are the proposed solutions, what tradeoffs does each involve, and which approach are we recommending?
The discipline of writing a design doc before writing code is one of the clearest separators between senior and staff-level thinking. As Google's design doc culture describes it: the goal of the design doc is not to get approval to build something. It's to surface assumptions that are wrong before you've spent three months building on them.
At Google, design docs for significant changes are reviewed by multiple engineers and result in documented feedback. The author is expected to incorporate that feedback before work begins. By the time code is written, the major architectural risks have already been identified and addressed.
For your career, writing design docs builds two things simultaneously:
Technical clarity. If you can't write a coherent design doc for a system you're proposing to build, you don't fully understand it yet. The writing process surfaces gaps in your thinking that a pull request review never would.
Organizational visibility. A design doc reviewed by 8 engineers means 8 people have now seen your thinking. One of them will remember your name when a staff role opens up, or when someone asks "who would know how to approach this kind of problem?"
A basic design doc outline:
- Problem statement — What's broken or missing, and why now?
- Background — Context someone unfamiliar with the system needs to follow the document
- Proposed solution — What you're building and how it works
- Alternatives considered — At least two. If you didn't consider alternatives, your proposal isn't ready.
- Open questions — The things you still don't know, named explicitly
- Success metrics — How you'll know it worked
That last point is underappreciated: stating success metrics in a design doc before you build something shows you understand that the outcome matters more than the implementation. That's exactly what promotion committees are looking for.
4. The RFC (Request for Comments)
An RFC is a design doc with a formal feedback mechanism. Where a design doc is often a proposal within a single team or for a single system, an RFC explicitly invites cross-team input on decisions that will affect multiple parties.
The RFC format was popularized in software by the IETF (the original RFCs that defined how the internet works) and has been adapted by companies like Rust, Stripe, HashiCorp, Squarespace, and Figma for internal technical governance.
When should you write an RFC instead of a design doc?
- The decision affects multiple teams or services
- You're proposing a new standard, convention, or process others will have to follow
- The change is hard to reverse and warrants broad buy-in
- You want explicit documented record of feedback from stakeholders
The career leverage of RFCs is asymmetric: you can write an excellent RFC and get it adopted by three other teams while touching zero lines of code outside your own service. That's pure organizational impact — and it shows up exactly the way a promotion packet needs it to.
Tanya Reilly's The Staff Engineer's Path recommends keeping an RFC template with these sections: Problem statement, Background, Proposal, Alternatives, Open questions, Success criteria, and Appendix (supporting data, links to related docs). That structure works at 10 engineers or 1,000.
The Writing-Promotion Pipeline (In Practice)
Here's what this actually looks like when it's working:
Year 1 as a senior engineer: You write ADRs for every non-trivial technical decision your team makes. You keep your service README current. You write your first design doc for a medium-complexity feature and share it with your team for review.
Year 2: You start writing design docs for larger features before you've scoped the work. Teammates outside your squad start reading your docs and leaving comments. You write your first RFC for a proposal that touches two other teams.
Year 3: Your design docs are referenced in other teams' documents. Engineers from other squads ask you to review their proposals because your written feedback is useful. You have a body of 15+ documented decisions with timestamps, tradeoffs, and outcomes. Your promotion packet writes itself.
The compounding effect is real. Each document you write slightly expands your visibility. Engineering managers and staff engineers notice when someone's name appears on multiple design docs across multiple systems. That's different from being known for a specific codebase — it signals someone who can operate at organizational scope.
Writing for Interview Artifacts
Your technical writing doesn't just help with internal promotions. It helps you interview.
When you're job-searching at senior or staff level, interviewers will often ask about system design decisions, architectural tradeoffs you've navigated, and technical challenges you've led. Engineers who have been writing design docs and ADRs have immediate, specific, documented answers to these questions. Engineers who only have code have to reconstruct the thinking from memory — which is harder and less convincing.
Some companies ask candidates to submit a writing sample as part of the interview process. A design doc you wrote for a real production system is dramatically more compelling than a homework assignment.
The portfolio angle also matters: your engineering portfolio can include links to public design docs, open-source RFCs you've authored, or sanitized versions of internal documents if your employer permits. It's a visible proof of the thinking that most engineers never surface.
If you're aiming for a senior-to-staff transition, a curated set of design docs and ADRs alongside your resume code bullets is evidence of staff-level thinking — the kind no resume template can generate.
Getting Started Without Institutional Pressure
The single most common reason engineers don't write design docs is that their company doesn't require them. "We just write the code" is the cultural default at a lot of teams, and going against it feels like overhead.
Here's how to start building the habit regardless of company culture:
Start with ADRs. They're the lowest overhead format and the hardest for anyone to object to — you're just writing down why you made a decision. Start with one per sprint for decisions that would otherwise live only in Slack history.
Write a "pre-mortem doc" before your next feature. Before you start coding, write one page: what could go wrong, what dependencies might break, what assumptions you're making. Share it with your team. This is 80% of a design doc without the formality.
Propose an RFC for something small. Pick a process or convention that's been informally debated — naming conventions, error handling patterns, test coverage expectations — and write a short RFC. Even if the proposal doesn't get adopted, you've practiced the format and made your thinking visible.
Make your README a habit, not a cleanup task. Every time you open a service, spend five minutes asking: "Is this README still accurate?" Treat documentation rot the same way you treat tech debt.
TL;DR
- Technical writing is the primary mechanism for operating beyond your immediate team. Code doesn't travel. Documents do.
- Four formats do most of the work: READMEs (service clarity), ADRs (decision records), design docs (pre-implementation planning), and RFCs (cross-team alignment).
- Design docs and RFCs compound. Every document you write expands your organizational visibility. After two years of consistent writing, your promotion packet has evidence across dozens of decisions.
- Writing forces clarity. If you can't write a coherent design doc for something you're proposing to build, you don't fully understand it yet.
- Technical writing is an interview artifact. At senior+ levels, your written record of decision-making is evidence that spoken answers about "a time you led a technical decision" can't match.
- Start without institutional pressure. ADRs require no process change. A pre-mortem doc requires no approval. Build the habit before you need it.
The engineers who operate at staff scope are writing constantly — proposals, decisions, context documents, postmortems, architecture reviews. The writing isn't the overhead. It's the work.
Related: The Senior-to-Staff Resume — how to reframe your existing documentation work as staff-level evidence in a resume.
Related: Your Engineering Portfolio Guide — where to surface your design docs, ADRs, and technical writing samples as interview artifacts.
Related: How to Turn Your GitHub Commit History Into Resume Bullets — technical writing and code commits are two sides of the same career capital.
Wrok builds your professional profile from your GitHub history, work experience, and technical artifacts — including design docs and writing samples. Start telling the full story of your engineering career. Try it free →