LabHub

ブログ

開発者ライティング完全ガイド: Design Doc、RFC、ブログ、書籍、カンファレンス発表まで (2025)

2026-04-15 · 24 分で読めます · #writing#design-doc#rfc#tech-blog#conference-talk#documentation#staff-plus#career#communication#deep-dive#japanese

한국어English日本語

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

5年目のSenior Engineer:

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

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

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

この記事は:

  1. Design Doc — 構造、テンプレート、失敗パターン
  2. RFCプロセス — Rust/Python/Node比較
  3. 技術ブログ — Julia Evans、Dan Luu、Stratecheryの解剖
  4. 技術書 — O'Reilly、Manning、セルフパブリッシング
  5. カンファレンス発表 — CFPから本番まで
  6. Staff+ 昇進パケット
  7. AI時代のライティング — Claude/Copilot活用法
  8. 韓国語 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の特徴

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

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

1.5 レビューを受ける

レビュアー選定:

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

フィードバック処理:

1.6 実例 — Amazonのnarrative memo

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

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プロセス

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

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

2.3 PythonのPEP

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

2.4 Node.jsのTSC

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

2.5 IETF RFC vs Project RFC

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

2.6 RFCを書くときのコツ

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

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

3.1 なぜブログなのか

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

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分析

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

3.4 Dan Luu分析

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

3.5 Stratechery(Ben Thompson)

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

3.6 ブログを始める

プラットフォーム選択:

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

3.7 ネタ探し

3.8 発行頻度

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

3.9 SEOと配信

SEO:

配信:

Chapter 4: 技術書の出版

4.1 出版社選び

O'Reilly:

Manning:

Pragmatic Bookshelf:

Packt:

Self-publishing(Leanpub、Gumroad):

4.2 本を書く時間

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

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

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

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

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

4.4 成功例 — Rust関連の書籍

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

4.5 文章の進化経路

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

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

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

5.1 なぜ発表なのか

5.2 CFP (Call for Proposal)

良いアブストラクト:

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

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

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

5.5 発表準備

8〜12週間前:

6週間前:

2週間前:

当日:

5.6 スライドデザイン

5.7 Q&A対応

5.8 成功例 — Bryan Cantrill(Oxide CTO)

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

Chapter 6: Staff+ 昇進パケット

6.1 Google Promo Packet

6.2 構成

  1. Summary: 一行の推薦
  2. Impact: 6〜12ヶ月間の主要貢献
  3. Complexity: 技術的難易度
  4. Scope: チーム → 組織 → 会社レベル
  5. Leadership: メンタリング、面接、外部
  6. 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の重要性

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

6.5 Peer Feedback依頼

6.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を使う際の倫理

7.4 Copilot in Writing

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

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

Chapter 8: 韓国語 vs 英語

8.1 韓国語だけで書く場合

メリット:

デメリット:

8.2 英語だけで書く場合

メリット:

デメリット:

8.3 韓英併行戦略

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

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

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

8.5 良い韓国語ブログの例

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

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

Chapter 9: 良いDocumentation

9.1 Divioの4つの文書タイプ

Divio Documentation Systemが提案:

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

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

9.2 良いREADME

9.3 Changelog

9.4 APIドキュメント

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

10.1 毎日100語

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

10.2 読むこと = 書くこと

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

おすすめの読書:

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

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は:

次回に続く。

コメント

まだコメントはありません。

ログインするとコメントできます