Chaos and Order

💡 왼쪽 원문을 읽으면서 오른쪽에 따라 써보세요. Tab 키로 힌트를 받을 수 있습니다.

はじめに — 「コーディングは最強なのに、なぜ昇進しない?」

5年目のSenior Engineer:

「技術力はチーム最強。コード品質もトップ。でもStaff昇進パケットで毎回落ちる」

答え: Staff+ レベルは文章で評価される。あなたが書いたdesign doc、postmortem、RFC、ブログ、メモがあなたの影響力。1万行のコードより、よく書かれたdesign doc 1枚の方が昇進に有利。

Googleの有名な社内調査: Staff+ レベルのライティング時間は30〜50%。「開発者」というより「テクニカルライター」。

この記事は:

Design Doc — 構造、テンプレート、失敗パターン
RFCプロセス — Rust/Python/Node比較
技術ブログ — Julia Evans、Dan Luu、Stratecheryの解剖
技術書 — O'Reilly、Manning、セルフパブリッシング
カンファレンス発表 — CFPから本番まで
Staff+ 昇進パケット
AI時代のライティング — Claude/Copilot活用法
韓国語 vs 英語 — 韓国人開発者の戦略

を扱う。Season 3 Episode 7。前回はOSSメンテナーのREADMEだったが、今回はさらに広く 開発者のあらゆる文章 を包括する。

Chapter 1: Design Doc — コードを書く前に書く文章

1.1 Design Docとは

Googleが1999年ごろから定着させた文化。複雑度のあるコードを書く前に 4〜30ページの文書を作成しレビュー する。

目的:

思考の明確化(文章にできなければ理解していない)
より良いレビュアー意見の収集
組織学習(将来検索可能)
新人オンボーディング教材

1.2 GoogleのDesign Docテンプレート

1. Title
2. Author(s) + Date + Status
3. Summary (1 paragraph, 해결 문제 + 제안)
4. Background (용어, 현재 시스템, 문제)
5. Goals / Non-Goals
6. Design Overview (그림 + 주요 컴포넌트)
7. Detailed Design
   - Data Model
   - API
   - 알고리즘
   - 에러 처리
8. Considered Alternatives (대안 2-3개 + 비교 + 왜 선택 안 함)
9. Cross-cutting Concerns (보안, 프라이버시, 성능, 비용, 관측)
10. Rollout Plan (단계, 롤백, 마이그레이션)
11. Open Questions
12. Appendix (Raw data, 벤치마크)

1.3 良いDesign Docの特徴

問題から始める: 何が、なぜ問題か。「マイクロサービスを導入しよう」ではなく「デプロイ時間が45分 → ユーザー不満」
測定可能な目標: 「より速く」ではなく「p99 < 200ms」
代替案の正直な比較: 「我々のが最高」ではなく「Aは速いがコスト2倍、Bは安いが複雑度が高い」
反対意見の反映: FAQセクションで「こう考えるかもしれませんが...」
数字で根拠: ベンチマーク、コスト見積もり、QPS見積もり

1.4 悪いDesign Docによくある失敗

「What」のみで「Why」がない: 何をするかだけで、なぜやるかが抜けている
分量が多すぎる: 50ページ → 誰も読まない
分量が少なすぎる: 1ページ → 詳細が不足
用語の混乱: 同じ概念を異なる名前で
結論がない: 議論だけで決定がない

1.5 レビューを受ける

レビュアー選定:

直接影響を受けるチームのTech Lead
Cross-functional(Security、SRE)
Staff+ エンジニア(全体方向性のチェック)

レビュー期間: 1〜4週間。短すぎるとフィードバック不足、長すぎるとタイミングを逃す。

フィードバック処理:

すべてのコメントに返信(同意 / 部分同意 / 反対)
大きな変更はchangelogに記録
未解決の問題はOpen Questionsへ

1.6 実例 — Amazonのnarrative memo

Amazonは6ページのnarrative memo。構造は緩いが:

叙述型の文章(bullet禁止)
具体的なデータ
反対意見への先回り対応(FAQ)
顧客視点

Jeff Bezosの評価基準:

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

Chapter 2: RFC — コミュニティ単位の意思決定

2.1 RFCが必要な場面

複数チーム/組織に影響
破壊的変更の可能性
長期的方向性に重要
外部コミュニティの合意が必要

Design Docはチーム/組織内部。RFCは より広いコミュニティ + 正式プロセス。

2.2 RustのRFCプロセス

Discussion: Rust Internals forumでのアイデアブレインストーミング
PR提出: rust-lang/rfcs リポジトリにMarkdownのPR
コミュニティ議論: 数週間〜数ヶ月
Final Comment Period (FCP): 10日間の最終意見募集
Merge or Postpone: Core teamの合意

公開されている例: async/await、GAT(Generic Associated Types)、const generics。

2.3 PythonのPEP

PEP 1: プロセス自体
PEP 8: スタイルガイド
PEP 20: Zen of Python
PEP 8016: Steering Councilモデル

PEPはRustよりもフォーマル。有名なPEP:

PEP 492(async/await追加)
PEP 572(walrus operator :=)
PEP 657(Fine-grained error locations)

2.4 Node.jsのTSC

NodeはRFCの代わりに TSC(Technical Steering Committee) の投票 + Collaborator合意。

小さな変更: Collaborator PR
大きな変更: TSC会議 + 投票

2.5 IETF RFC vs Project RFC

混同注意: IETF RFC(インターネット標準、HTTP/TCP等)とプロジェクトRFCは別物。

IETF: インターネット標準文書。永続的な番号。例: RFC 9110(HTTP/1.1)
Project RFC: 個別プロジェクトの提案書。

2.6 RFCを書くときのコツ

ワンショット完璧を避ける: ドラフト公開、フィードバック反映、複数バージョン
動機の十分な説明: 「なぜ今、なぜこの方式」
Alternative considered: 必須
Migration path: 破壊的変更ならマイグレーション経路
Backwards compatibility: 互換性を明示

Chapter 3: 技術ブログ — 長期資産

3.1 なぜブログなのか

Staff+ エンジニアの共通点: ブログ。理由:

ライティング練習: 最も安価なトレーニング
思考の整理: 書きながら理解が深まる
ネットワーク: 読者 → 同僚 → 機会
検索流入: Google経由で機会がやってくる
昇進の証拠: 外部への影響力

3.2 ブログのタイプ

1) Deep-diveタイプ: 1つのテーマに1万字。例: Julia Evansの「How does a database work?」

2) Notesタイプ: 学んだことを素早く整理。例: Simon Willisonのweblog。

3) Opinionタイプ: 業界分析。例: Stratechery(Ben Thompson)、Overreacted(Dan Abramov)。

4) Tutorialタイプ: Step-by-step。例: Josh Comeau、Kent C. Dodds。

5) Newsletterタイプ: 定期的キュレーション。例: Pointer、TLDR。

3.3 Julia Evans分析

2013年にブログ開始
特徴: 漫画のような技術解説(「zines」)
テーマ: Linux、systems、debugging
収入: zines販売( $20〜$ 40)、Ruby Centralコンサルティング
2022年にStripeを退社 → 専業作家に

教訓: 専門領域 + 独特なスタイル = ファンダム。

3.4 Dan Luu分析

Stack / hardware / performance専門
特徴: 長文(1〜3万字)、論文レベルのリサーチ
「Why are computers slow?」などのdeep research
年間20本前後
収入: 主に本業(Microsoft → Twitter → 現在)

教訓: 希少テーマ + 深さ = 権威。

3.5 Stratechery(Ben Thompson)

テックビジネス分析blog + podcast
$12/月 subscription モデルで独立
年数百万ドルと推定
「Aggregation Theory」のようなフレームワークを提示

教訓: ニュースを追わず分析フレームワークを作る。

3.6 ブログを始める

プラットフォーム選択:

セルフホスト: Next.js + Vercel、Astro、Hugo(このブログのように)
Medium: 簡単、発見されやすい、しかし所有できない
Substack: ニュースレター + ブログ結合
dev.to: 開発者コミュニティ
Hashnode: カスタムドメイン無料

セルフホスト推奨: 長期資産は自分のものであるべき。

3.7 ネタ探し

最近自分が学んだこと(最良 — 説明することで定着)
よく受ける質問
誤って知られていることの訂正
業界論争に自分の意見を加える
Deep-diveした1テーマ(他ブログ/論文10本 + 自分の経験)

3.8 発行頻度

週1〜2本: 忙しすぎる、品質低下
月1〜2本: 持続可能、品質維持
四半期1本: 深いlong-form

一貫性 > 量。毎週ヒーヒーするより月1本の良質。

3.9 SEOと配信

SEO:

タイトルにキーワード
Descriptionメタ
H2/H3構造
内部リンク(関連記事)
画像alt

配信:

Twitter/X
Hacker News(適切な時間帯: 平日米国午前)
Reddit(関連サブ)
LinkedIn(業界読者)
Slackコミュニティ

Chapter 4: 技術書の出版

4.1 出版社選び

O'Reilly:

業界最高ブランド(「動物の本」)
アドバンス $10K〜$ 30K
ロイヤリティ 10〜15%
編集が厳しい、ブランド活用可
出版まで1〜2年

Manning:

実用書中心
Early Access Program(MEAP): 未完成でも販売
読者フィードバックが速い
O'Reillyよりハードルが低い

Pragmatic Bookshelf:

プログラマー対象
技術的深さ
著者フレンドリーな条件

Packt:

素早い出版、多作
品質のばらつきが大きい

Self-publishing(Leanpub、Gumroad):

ロイヤリティ 80〜95%
完全な自己管理
マーケティングも自分の仕事

4.2 本を書く時間

現実: 平均1000〜1500時間。18ヶ月基準で週15時間(平日夜 + 週末)。

** $30K のアドバンス** を時給換算すると$ 20〜$30。本業よりはるかに少ない。

なぜ書くのか?: 金ではなく ブランド、権威、キャリア。著者のタイトルは生涯モノ。

4.3 成功例 — DDIA(Designing Data-Intensive Applications)

Martin Kleppmann著
O'Reilly 2017年
20万部以上販売
シリコンバレー面接対策の必読書
著者はケンブリッジのリサーチャー + 複数のコンサルティング

秘訣: 1分野(分散システム)の決定版。

4.4 成功例 — Rust関連の書籍

The Rust Programming Language(無料 + 有料出版)
Rust for Rustaceans(Jon Gjengset)
Programming Rust(O'Reilly)
Zero to Production in Rust(Luca Palmieri、self-publish)

教訓: 公式書 + 深掘り + 応用の組み合わせ。

4.5 文章の進化経路

블로그 글 → 시리즈 → eBook → 종이책
     ↓
  컨퍼런스 발표 → 강의 → 북

ブログの反応が良ければ拡張。ビッグバン出版より段階的成長。

Chapter 5: カンファレンス発表

5.1 なぜ発表なのか

ブログの20倍のインパクト(集中した聴衆)
YouTubeによる永久資産化
ネットワークの爆発的拡大
昇進パケットの大きな武器

5.2 CFP (Call for Proposal)

発表タイトル + アブストラクトを提出
合格率5〜20%(有名カンファレンス)
アブストラクトの質が合否を左右

良いアブストラクト:

具体的なタイトル(「我々がXをYに転換して学んだこと」)
問題 + 解決 + 教訓
聴衆のtakeawayを明示
発表者のクレデンシャル

5.3 韓国の主要カンファレンス

FEConf: フロントエンド
JSConf Korea: JavaScript
PyCon Korea: Python
SIF (Samsung Innovation Forum)
NHN FORWARD
NAVER DEVIEW
Kakao if(kakao)
Woowacon: Baemin
Toss PLANET

5.4 グローバルカンファレンス

KubeCon (CNCF): K8s / cloud-native
Strange Loop (2023終了): deep CS
QCon: 実務中心
RustConf、GopherCon、PyCon、RubyConf
JSConf、React Summit、Next.js Conf
Monktoberfest: 開発者カルチャー / キャリア

5.5 発表準備

8〜12週間前:

アブストラクト提出
初稿スライド

6週間前:

内部リハーサル(同僚2〜3名)
デモスクリプト

2週間前:

外部リハーサル(類似コミュニティ)
タイムチェック

当日:

1時間早く到着
機材テスト
バックアップノートPC

5.6 スライドデザイン

1アイデア = 1スライド
テキスト最小限(発表者が話す)
フォント28pt以上
高解像度スクリーンショット
複雑なアーキテクチャは複数段階でビルドアップ

5.7 Q&A対応

答えが分からなければ「良い質問ですが確信がないので後で共有します」でOK
論争的な質問: 感情を排する
長い質問: 要約してから回答

5.8 成功例 — Bryan Cantrill(Oxide CTO)

Sun MicrosystemsでDTraceを共同開発
発表がストーリー形式、ユーモア強め
「Scheduling Policy Hang」のような技術ドラマ
YouTube再生数は数十万超

教訓: 技術 + ストーリーテリング。

Chapter 6: Staff+ 昇進パケット

10〜50ページ
マネージャー + 本人で共同作成
4〜7名のpeer review
Calibration committeeの審査

6.2 構成

Summary: 一行の推薦
Impact: 6〜12ヶ月間の主要貢献
Complexity: 技術的難易度
Scope: チーム → 組織 → 会社レベル
Leadership: メンタリング、面接、外部
Feedback: peerコメント

6.3 各貢献を記述するフォーマット(STAR format)

Situation: 文脈 Task: 自分の責任 Action: 自分が行った行動 Result: 測定可能な結果

例:

「[S] 決済システムのp99が800msで、ユーザー離脱率12%。 [T] Staff Engとしてパフォーマンス改善のオーナーシップ。 [A] 分散キャッシュ導入 + クエリ最適化 + async処理。 [R] p99 150ms、離脱率5%減、売上 $2M 増加」

6.4 Scopeの重要性

Senior: チームの問題解決
Staff: チームを超えて影響
Senior Staff: 組織全体
Principal: 会社全体

同じプロジェクトでも「一人で作った」vs「5チームと協業して標準化した」で説明が違う。

6.5 Peer Feedback依頼

多様な視点(上 / 下 / 同級)
具体的事例をお願い
量より質

6.6 落ちた後

マネージャーと率直な会話
ギャップの把握(Impact? Leadership? Writing?)
6ヶ月計画の策定
次サイクルで再挑戦

Chapter 7: AI時代のライティング

7.1 AIでやってはいけないこと

全文生成: すぐバレる、個性がない
雑な出力をコピペ: ハルシネーションのリスク
自分の考えなしに依存

7.2 AIが役立つこと

1) アイデアブレインストーミング:

"이 Design Doc 주제로 대안 3가지만 제안해줘. 장단점 포함."

2) 構造フィードバック:

"이 블로그 초안의 논리 구조 약점을 지적해줘."

3) 文法/不自然さの修正:

"이 문장을 자연스러운 영어로 다듬어줘. 원래 뜻 유지."

4) 想定質問:

"이 RFC에 기술 리드가 할 수 있는 반론 5개."

5) 要約作成:

"긴 포스트의 TL;DR 3줄."

7.3 AIを使う際の倫理

開示: 「このドラフトはAIの助けを借りた」と宣言
ファクトチェック: AIの出力は必ず確認
個性維持: 自分の文体を優先

7.4 Copilot in Writing

VS CodeでMarkdownも自動補完
文の完成、箇条書きの生成
注意: 文を完成させてくれるが、意味は自分で決める

7.5 Claude / GPT活用ワークフロー

自分: ドラフトを書く
AI: 構造フィードバック
自分: 修正
AI: 文法 / 表現の磨き
自分: 最終確認、個性復元
AI: タイトル10案 → 自分: 1つ選ぶ

Chapter 8: 韓国語 vs 英語

8.1 韓国語だけで書く場合

メリット:

韓国人読者に100%届く
感情、ニュアンスが自由
コミュニティとの距離が近い

デメリット:

グローバル機会が限定的
世界的ブランド構築が難しい

8.2 英語だけで書く場合

メリット:

グローバル読者
海外採用 / コンサル有利
英語力の向上

デメリット:

韓国人読者が減る
初期がつらい

8.3 韓英併行戦略

オプションA: 英語原稿 → 韓国語訳要約 オプションB: 韓国語原稿 → 英語短い要約 オプションC: テーマ別言語分け(ローカル課題は韓国語、グローバル課題は英語)

このブログのように 完全バイリンガル も可能だが、手間がかかる。

8.4 韓国人開発者の英語ライティングのコツ

短文中心: 複雑な関係詞節を避ける
能動態: "We decided to..." > "It was decided that..."
明晰さ > 華やかさ: 難しい単語 ≠ 良い文章
校正ツール: Grammarly、Claude、DeepL Write

8.5 良い韓国語ブログの例

朴宰星(Javajigi)
金泳漢(Inflearn講義 + ブログ)
Woowahan Brothers技術ブログ
Kakao Techブログ
Toss Techブログ
Daangn技術ブログ

8.6 英語で発信する韓国人開発者の例

Dan Luu(映像インタビュー、Twitter)
Evan You(Vue創始者、中国系だがグローバル)
Jaejin Kim / Jake Seoなど海外で活動する韓国人開発者(少数)

韓国人開発者による英語ブログの活性化はまだ余地が大きい。

Chapter 9: 良いDocumentation

9.1 Divioの4つの文書タイプ

Divio Documentation Systemが提案:

Tutorials: 学ぶため(初心者向け)
How-to guides: 特定タスクの完了
Reference: 正確な技術情報
Explanation: 背景、なぜ

4つを混ぜると混乱。分離して書く。

9.2 良いREADME

Hero: 何をするプロジェクトか1行
Install: 3行以内でスタート
Quickstart: コード例
Badges: CI、バージョン、ライセンス
Table of Contents: 長い場合
Contributing、License、Acknowledgments

9.3 Changelog

Keep a Changelog スタイル
Added / Changed / Deprecated / Removed / Fixed / Security
ユーザー中心の表現(「Breaking: ...」を明示)

9.4 APIドキュメント

OpenAPI / Swagger 自動生成
リクエスト / レスポンス例は必須
エラーコード全リスト
レートリミットの明示

Chapter 10: ライティング筋力を鍛える

10.1 毎日100語

重要なのは 一貫性。毎日100語 = 年間36,500語 ≈ ブログ30〜40本。

10.2 読むこと = 書くこと

良い文章を読む。分析しながら読む。「この文はなぜこう書かれたか」を考える。

おすすめの読書:

Paul Grahamのエッセイ(簡潔さ)
Dan Luu(深さ)
Julia Evans(明晰さ)
Simon Willison(継続性)

10.3 フィードバックをもらう

同じく書いている同僚
Discord / Slackのライティングチャンネル
家族 / 友人(非専門家が理解できるか)

10.4 推敲の技術

1回目: 意味が通るか 2回目: 構造が明瞭か 3回目: 単語が正確か 4回目: リズムが自然か

最低1日寝かせてから 読み直す。

Chapter 11: ライティングアンチパターン10

1)「なぜ」を抜かす

何をするかだけで、なぜやるかがない。「Why」が先、「What」が後。

2) jargon乱発

読者が知らない用語を説明なしで使用。初出時に説明。

3) 受動態の過剰使用

「決定された」より「チームが決定した」。主体を明確に。

4) bullet乱用

すべての文がbullet。叙述がない。段落の散文が論理を強制する。

5) hedge語

「maybe」「perhaps」「might」。自信不足。確信があるなら断言。

6) 不要な前置き

「本記事ではこのような内容を扱う予定です」は悪い導入。直ちに本題。

7) 図がない

アーキテクチャ図、シーケンス図がない。Excalidraw / Mermaidを活用。

8) 結論がない

議論だけ長く、「だから何?」がない。Call to actionまたはtakeaways。

9) 校正の省略

誤字、文法ミス。信頼を損なう。公開前に2回読む。

10) オーディエンスの混乱

初心者向けか専門家向けか不明確。最初の段落で明示。

Chapter 12: 12項目ライティングチェックリスト

おわりに — ライティングはエンジニアリングスキル

原則1: 書くこと = 考えること

書けなければ理解していない。Einstein: "If you can't explain it simply, you don't understand it well enough."

原則2: 頻繁に書く > 上手く書く

完璧主義を捨てる。最初の100本はぎこちなくても継続。複利効果。

原則3: 多様な形式

Design Doc、RFC、blog、book、talk — 形式ごとに筋肉がある。1つだけ得意では頭打ち。

原則4: フィードバックが最速の成長

同僚 / 読者のフィードバックを積極的に求める。恥ずかしさを乗り越える。

原則5: 真摯さ > 華麗さ

飾らない経験談が最高のコンテンツ。失敗談の共有をためらわない。

原則6: 原本を読め

次回予告 — 「開発者財務完全ガイド: 年収、ストックオプション、RSU、401k、起業資金まで」

Season 3 Ep 8は:

年収交渉の科学(Levels.fyi、Blind活用)
RSU vs Stock Option: 行使タイミング、税金
ESOPと韓国税法
401k / IRA(米国)、退職年金(韓国)
スタートアップの持分 — Vesting Cliff、Exitシナリオ
不動産 vs 株式 vs 会社持分
米国進出時の税務(H1B、L1ビザ問題)
FIRE (Financial Independence Retire Early)
起業時の資金フローと希釈
40代開発者の財務計画

次回に続く。