良い PR と README を書く
なぜ技術ライティングが重要なのか
Section titled “なぜ技術ライティングが重要なのか”コードレビューでは、PR の説明はレビュアーの入口です。良い PR の説明は：
- レビュアーがあなたのやったことをすばやく理解できる
- やり取りの質問を減らせる
- あなたが慎重に考えたことを示す
- 3 ヶ月後に履歴を確認するときに時間を節約する
同様に、良い README は：
- 新メンバーがすばやく始められる
- 繰り返しの質問を減らす
- プロジェクトをプロフェッショナルに見せる
PR 説明の標準構造：What/Why/How/Testing
Section titled “PR 説明の標準構造：What/Why/How/Testing”1. What（何をしたか）
Section titled “1. What（何をしたか）”簡潔なサマリー、1 文で。
Refactor authentication flow to support OAuth2 and magic link sign-upキー表現：
- Add X — 新機能の追加
- Fix X — バグの修正
- Refactor X — コードの書き直し（機能変更なし）
- Optimize X — パフォーマンスの改善
- Implement X — 設計の実装
2. Why（なぜやったか）
Section titled “2. Why（なぜやったか）”最も見落とされがちな部分です。背景と動機を説明します。
Why:- Users requested passwordless sign-up option- Current session-based auth doesn't scale to multiple domains- OAuth2 is industry standard for enterprise integrations良い Why の特徴：
- ビジネス上の理由に言及している（ユーザーニーズ、パフォーマンス、メンテナンス性）
- 既存のソリューションがなぜ不十分かを説明している
- このソリューションがなぜ良いかを述べている
3. How（どのように実装したか）
Section titled “3. How（どのように実装したか）”技術実装のハイレベルな概要です。行ごとの説明は不要です（それはコードレビューの仕事です）が、レビュアーに全体のアーキテクチャを知らせる必要があります。
How:1. Created JWT service using Web Crypto API for signing/verification2. Replaced SessionMiddleware with AuthMiddleware that validates JWT3. Added OAuth2 routes for Google/GitHub sign-in4. Migrated user session storage from cookie to JWT claims5. Added magic link generation and validation
Breaking changes:- Moved user auth state from server session to JWT (stateless)- Clients now need to store and send JWT in Authorization header4. Testing（どのようにテストしたか）
Section titled “4. Testing（どのようにテストしたか）”Testing:- Manual testing: Verified OAuth2 sign-in with Google and GitHub accounts- Existing auth tests pass (147 tests)- Added 23 new tests for JWT and OAuth2 flows- Load tested with 1000 concurrent requests (no issues)技術ライティングの文法の落とし穴
Section titled “技術ライティングの文法の落とし穴”1. 時制（最もよくある間違い）
Section titled “1. 時制（最もよくある間違い）”原則：現在形でコードの機能を、過去形で行った変更を表現する
| 間違い | 原因 | 正しい |
|---|---|---|
| ”The function was created to handle X” | 歴史の叙述に聞こえる | ”The function handles X" |
| "The code will validate input” | 不確かすぎる | ”The code validates input" |
| "We added the feature” (README 内) | README は歴史を語らない | ”This feature allows users to…“ |
2. 冠詞（日本語話者によくある間違い）
Section titled “2. 冠詞（日本語話者によくある間違い）”原則：初回は “a/an”、以降は “the”、または複数形で冠詞を避ける
| 間違い | 原因 | 正しい |
|---|---|---|
| ”We refactored authentication flow” | どの flow か不明確 | ”We refactored the authentication flow" |
| "Function handles case when user logs in” | 日本語式、“the” が欠落 | ”The function handles the case when a user logs in” |
3. 受動態の過剰使用
Section titled “3. 受動態の過剰使用”原則：英語はより能動態を好む。誰がやったか言いたくない場合を除き、能動態を使う
| 受動（日本語干渉でよくある） | 能動（より良い） |
|---|---|
| “The JWT is generated by the server" | "The server generates the JWT" |
| "The user data is stored in D1" | "We store user data in D1" |
| "Breaking changes were introduced" | "This PR introduces breaking changes” |
4. 同義語の微妙な違い
Section titled “4. 同義語の微妙な違い”| 語彙 | 用法 |
|---|---|
| Add | 新機能の追加（全く存在しなかった）: “Add OAuth2 support” |
| Implement | 既知の設計の実装: “Implement the design from #123” |
| Create | 新しいオブジェクトの生成: “Create JWT service” |
| Build | システムの構築: “Build the CI/CD pipeline” |
| Refactor | 既存コードの改善、機能変更なし: “Refactor auth middleware” |
| Optimize | パフォーマンスの向上: “Optimize query performance” |
| Fix | バグの修正: “Fix race condition in cache” |
PR 説明のクイックチェックリスト
Section titled “PR 説明のクイックチェックリスト”PR を送信する前にチェック：
- What セクションが変更を明確に説明している
- Why セクションにビジネスまたは技術的な理由がある（「やりたかったから」だけではない）
- How セクションにハイレベルな設計があり、レビュアーがコードを行ごとに読む必要がない
- Testing セクションにテストカバレッジを記述している
- 受動態が過剰でない
- 冠詞が正しい（“the” vs “a”）
- 時制が一貫している（現在形でコードの機能、過去形で変更）
- 関連する issue にリンクしている（ある場合）
README のクイックチェックリスト
Section titled “README のクイックチェックリスト”- 冒頭の 1 文でプロジェクトが何かを明確にしている
- デモまたはスクリーンショットがある
- インストール手順が明確で再現可能
- 使用例がそのままコピーできる
- コントリビューティングガイドがある（外部からの貢献を受け入れる場合）
- ライセンスがある
- 言語が簡潔（学術的すぎずカジュアルすぎず）