LabHub

Blog

The Complete Developer Writing Guide: Design Doc, RFC, Blog, Book, Conference Talk (2025)

2026-04-15 · 17 min read · #writing#design-doc#rfc#tech-blog#conference-talk#documentation#staff-plus#career#communication#deep-dive#english

한국어English日本語

Intro — "My coding is the best on the team. Why can''t I get promoted?"

A 5-year Senior Engineer:

"My technical skills are top on the team. My code quality is top. But every time, I get rejected for Staff promo."

The answer: Staff+ levels are evaluated by writing. The Design Docs, postmortems, RFCs, blog posts, and memos you''ve written — that''s your influence. A single well-written Design Doc helps more with promotion than 10,000 lines of code.

A well-known Google internal study: Staff+ engineers spend 30–50% of their time writing. They''re less "developers" and more "technical writers."

This post covers:

  1. Design Doc — structure, templates, failure modes
  2. RFC process — Rust/Python/Node compared
  3. Tech blogs — dissecting Julia Evans, Dan Luu, Stratechery
  4. Tech books — O'Reilly, Manning, self-publishing
  5. Conference talks — from CFP to the podium
  6. Staff+ promo packets
  7. Writing in the AI era — Claude/Copilot workflows
  8. Korean vs English — strategy for Korean developers

Season 3 Episode 7. The previous post covered OSS maintainer README files; this one zooms out to cover every form of developer writing.

Chapter 1: Design Doc — the writing that comes before the code

1.1 What is a Design Doc?

A Google-rooted culture since around 1999. Before writing non-trivial code, you write a 4–30 page document and get it reviewed.

Purpose:

1.2 Google''s Design Doc template

1. Title
2. Author(s) + Date + Status
3. Summary (1 paragraph: problem + proposal)
4. Background (terminology, current system, problem)
5. Goals / Non-Goals
6. Design Overview (diagram + main components)
7. Detailed Design
   - Data Model
   - API
   - Algorithms
   - Error handling
8. Considered Alternatives (2-3 alternatives + comparison + why not chosen)
9. Cross-cutting Concerns (security, privacy, performance, cost, observability)
10. Rollout Plan (stages, rollback, migration)
11. Open Questions
12. Appendix (raw data, benchmarks)

1.3 What a good Design Doc looks like

  1. Start from the problem: what is wrong and why. Not "let''s adopt microservices" but "deploy time is 45 min, users are complaining."
  2. Measurable goals: not "faster" but "p99 under 200ms."
  3. Honest alternative comparison: not "ours is the best" but "A is faster but costs 2x; B is cheaper but more complex."
  4. Address dissent: include a FAQ section that anticipates "you might be thinking..."
  5. Evidence via numbers: benchmarks, cost estimates, QPS estimates.

1.4 Common bad Design Doc mistakes

1.5 Getting it reviewed

Reviewer selection:

Review period: 1–4 weeks. Too short, insufficient feedback; too long, you miss the window.

Handling feedback:

1.6 Case study — Amazon''s narrative memo

Amazon uses a 6-page narrative memo. Less structural, but:

Jeff Bezos''s bar:

"A great memo reads like it was written by a good journalist covering a complex story."

Chapter 2: RFC — community-wide decisions

2.1 When you need an RFC

Design Docs stay within a team or org. RFCs target a broader community + a formal process.

2.2 Rust''s RFC process

  1. Discussion: brainstorm on Rust Internals forum
  2. Submit PR: Markdown PR to the rust-lang/rfcs repository
  3. Community discussion: weeks to months
  4. Final Comment Period (FCP): 10-day final feedback window
  5. Merge or Postpone: core team consensus

Public examples: async/await, GAT (Generic Associated Types), const generics.

2.3 Python''s PEP

PEPs are more formal than Rust RFCs. Notable PEPs:

2.4 Node.js TSC

Node uses no formal RFC; instead it relies on the TSC (Technical Steering Committee) vote + Collaborator consensus.

2.5 IETF RFC vs Project RFC

Don''t confuse them: IETF RFCs (internet standards like HTTP/TCP) and project RFCs are different beasts.

2.6 Tips when writing an RFC

  1. Don''t aim for a perfect one-shot: publish a draft, iterate across versions
  2. Motivate fully: "why now, why this approach"
  3. Alternatives considered: mandatory
  4. Migration path: if it breaks things, show the migration
  5. Backwards compatibility: state it explicitly

Chapter 3: Tech blog — long-term asset

3.1 Why blog?

A common trait among Staff+ engineers: a blog. Because it gives you:

3.2 Types of blogs

1) Deep-dive: 10,000+ words on one topic. Example: Julia Evans''s "How does a database work?"

2) Notes: quickly writing up what you learned. Example: Simon Willison''s weblog.

3) Opinion: industry analysis. Example: Stratechery (Ben Thompson), Overreacted (Dan Abramov).

4) Tutorial: step-by-step. Example: Josh Comeau, Kent C. Dodds.

5) Newsletter: regular curation. Example: Pointer, TLDR.

3.3 Julia Evans analysis

Lesson: niche expertise + distinctive style = fandom.

3.4 Dan Luu analysis

Lesson: rare topics + depth = authority.

3.5 Stratechery (Ben Thompson)

Lesson: don''t chase the news cycle; build analytical frameworks.

3.6 Starting a blog

Platform options:

Recommend self-hosting: long-term assets should be yours.

3.7 Finding topics

3.8 Publishing cadence

Consistency beats volume. One monthly quality piece beats five rushed weekly posts.

3.9 SEO and distribution

SEO:

Distribution:

Chapter 4: Publishing a tech book

4.1 Choosing a publisher

O'Reilly:

Manning:

Pragmatic Bookshelf:

Packt:

Self-publishing (Leanpub, Gumroad):

4.2 How long it takes

Reality: 1000–1500 hours on average. Over 18 months that''s 15 hours/week (weekday evenings + weekends).

A $30K advance works out to $20–$30/hour. Far less than your day job.

So why write one?: not the money — brand, authority, career. "Published author" is a lifetime asset.

4.3 Success story — DDIA (Designing Data-Intensive Applications)

Secret: the definitive book for one field (distributed systems).

4.4 Success story — Rust books

Lesson: official book + deep-dive + applied — the full combo.

4.5 The evolution path of writing

Blog post → Series → eBook → Print book
     ↓
  Conference talk → Course → Book

If a blog post resonates, expand it. Gradual growth beats a big-bang launch.

Chapter 5: Conference talks

5.1 Why speak?

5.2 CFP (Call for Proposal)

A good abstract:

  1. Specific title ("What we learned migrating X to Y")
  2. Problem + solution + lessons
  3. Explicit audience takeaways
  4. Speaker credentials

5.3 Major Korean conferences

5.4 Global conferences

5.5 Preparing the talk

8–12 weeks out:

6 weeks out:

2 weeks out:

Day of:

5.6 Slide design

5.7 Handling Q&A

5.8 Success story — Bryan Cantrill (Oxide CTO)

Lesson: technical depth + storytelling.

Chapter 6: Staff+ promotion packet

6.1 Google''s promo packet

6.2 Structure

  1. Summary: one-line recommendation
  2. Impact: major contributions over 6–12 months
  3. Complexity: technical difficulty
  4. Scope: team → org → company level
  5. Leadership: mentoring, interviewing, external work
  6. Feedback: peer comments

6.3 The STAR format for each contribution

Situation: context Task: your responsibility Action: what you did Result: measurable outcome

Example:

"[S] Payment system p99 was 800ms, user drop-off was 12%. [T] As Staff Eng, I owned the performance effort. [A] Added distributed caching, optimized queries, moved to async processing. [R] p99 dropped to 150ms, drop-off fell 5%, revenue up $2M."

6.4 Scope matters

Same project, different framing: "I built it alone" vs "I standardized it across 5 teams."

6.5 Requesting peer feedback

6.6 If you didn''t make it

Chapter 7: Writing in the AI era

7.1 What not to do with AI

7.2 What AI is great for

1) Idea brainstorming:

"Suggest 3 alternatives for this Design Doc topic, with pros and cons."

2) Structural feedback:

"Point out the logical weaknesses in this blog draft."

3) Grammar / awkward phrasing:

"Polish this sentence into natural English, keeping the meaning."

4) Anticipating questions:

"List 5 pushbacks a tech lead might have on this RFC."

5) Summary drafting:

"Write a 3-line TL;DR of this long post."

7.3 AI ethics

7.4 Copilot in writing

7.5 Claude/GPT workflow

  1. You: write a draft
  2. AI: structural feedback
  3. You: revise
  4. AI: grammar/phrasing polish
  5. You: final check, restore your voice
  6. AI: suggest 10 titles → you: pick one

Chapter 8: Korean vs English

8.1 Writing only in Korean

Pros:

Cons:

8.2 Writing only in English

Pros:

Cons:

8.3 Bilingual strategies

Option A: English original → Korean summary translation Option B: Korean original → short English summary Option C: Split by topic language (local issues in Korean, global issues in English)

A fully bilingual site like this blog is possible but expensive.

8.4 English writing tips for Korean developers

8.5 Good Korean-language blogs

8.6 Korean developers writing in English

English blogging by Korean developers is still wide open.

Chapter 9: Good documentation

9.1 Divio''s 4 documentation types

Divio Documentation System proposes:

  1. Tutorials: learning-oriented (for beginners)
  2. How-to guides: complete a specific task
  3. Reference: precise technical information
  4. Explanation: background and why

Mixing the four causes confusion. Write them separately.

9.2 A good README

9.3 Changelog

9.4 API docs

Chapter 10: Building writing muscle

10.1 100 words a day

Consistency is the point. 100 words per day = 36,500 per year ≈ 30–40 blog posts.

10.2 Reading = writing

Read good writing. Read analytically. Ask "why did they write this sentence this way?"

Recommended reading:

10.3 Getting feedback

10.4 The art of revision

Pass 1: does the meaning land? Pass 2: is the structure clear? Pass 3: are the words precise? Pass 4: does it flow?

Let it sit for at least a day before rereading.

Chapter 11: 10 writing antipatterns

1) Missing the "Why"

Only the "what," no "why." Why first, what second.

2) Jargon overload

Using terms the reader doesn''t know without definitions. Define on first use.

3) Passive-voice abuse

"It was decided" versus "The team decided." Make the actor clear.

4) Bullet overuse

Every sentence is a bullet. No narrative. Prose paragraphs force logical flow.

5) Hedging language

"maybe," "perhaps," "might." Lack of confidence. Assert when you''re sure.

6) Unnecessary preamble

"In this post I will cover the following topics..." is a weak intro. Go straight to the point.

7) No diagrams

Missing architecture or sequence diagrams. Use Excalidraw/Mermaid.

8) No conclusion

Long discussion with no "so what?" Add a call to action or takeaways.

9) Skipping proofreading

Typos and grammar errors erode trust. Read through twice before publishing.

10) Audience confusion

Unclear whether it''s for beginners or experts. State the audience in the first paragraph.

Chapter 12: The 12-item writing checklist

Closing — writing is an engineering skill

Principle 1: writing is thinking

If you can''t write it, you don''t understand it. Einstein: "If you can''t explain it simply, you don''t understand it well enough."

Principle 2: writing often beats writing well

Drop the perfectionism. The first 100 posts will be awkward — keep going. Compounding wins.

Principle 3: multiple formats

Design Doc, RFC, blog, book, talk — each is a different muscle. Mastering only one caps you.

Principle 4: feedback is the fastest path to growth

Ask peers and readers. Swallow the embarrassment.

Principle 5: authenticity over polish

Unvarnished experience is the best content. Don''t be shy about failure stories.

Principle 6: read the originals

Next post — "The complete developer finance guide: salary, stock options, RSU, 401k, startup funding"

Season 3 Ep 8 will cover:

See you in the next post.

Comments

No comments yet.

Sign in to leave a comment