ドキュメントを書く

新人が最初に評価されるのは、コードではなく文章です。

理由は単純で、あなたのコードを読む人は数人ですが、 あなたが書いた PR の説明・相談・設計ドキュメントは、 チーム全員が読むからです。そして読みにくい文章は、読まれません。

読まれなかった設計ドキュメントは、無いのと同じです。

この章では、実務で書く文書の型と、書き方の技術を扱います。

コードは「どう」しか語らない

コードを読めば、何をしているかは分かります。しかし次のことは、 どれだけ丁寧なコードを書いても伝わりません。

• なぜその方法を選んだのか
• 何を検討して捨てたのか
• どういう制約があってこうなっているのか
• この処理がいつまで必要なのか

これらは文章にしか残せません。だから設計ドキュメントを書き、 PR の説明を書き、コミットメッセージを書きます。

まず読み手を決める

すべての文章術は、これに集約されます。

誰が          → チームの他のエンジニア？ 未来の自分？ 非エンジニア？
いつ          → 今すぐ？ 半年後の障害対応中？
何のために    → 判断するため？ 手を動かすため？ 経緯を知るため？
読むのか

「半年後、深夜3時の障害対応中に読む人」を想定すると、 書くべきことがはっきりします。その人は焦っていて、前提知識がなく、 最後まで読む時間もありません。だから結論を最初に書きます。

実務で書く6種類

寿命が長い文書ほど、更新されないと害になります。 「そのうち直す」で放置された手順書は、障害時に人を迷わせます。

設計ドキュメント（デザインドック）

コードを書く前に、何を作るかを文章で合意するための文書です。 実装に何日もかかるものは、まずこれを書きます。

書くのが面倒に見えますが、実装後に「そもそも要らなかった」と言われるより はるかに安いというのが、これが広く使われている理由です。

型

# タイトル: 何を作るのか（1行で分かる名前）

## 背景 / 課題
今どういう状態で、何が困っているのか。
数字があれば必ず入れる（「遅い」ではなく「p99 が 3.2 秒」）。

## ゴール
これができたら成功、と言えることを箇条書きで。

## 非ゴール           ← ここが最も重要
今回はやらないこと。「将来的にはやるかもしれないが今回は対象外」を明示する。

## 提案する設計
図を1枚。それから、変更するコンポーネントごとに何をするか。

## 検討した他の案
案A / 案B を挙げ、なぜ採らなかったかを書く。

## リスクと影響
壊れうるもの、移行の手順、ロールバックの方法。

## 未解決の点
決まっていないこと、レビューで意見が欲しいところ。

ADR — 決定を1件1ファイルで残す

ADR（Architecture Decision Record）は、 「なぜそう決めたか」だけを短く残すフォーマットです。

# ADR-0007: セッション管理に JWT ではなく Redis を使う

## ステータス
承認済み（2026-08-08）

## 文脈
- ログアウトを即時に反映する要件がある
- 認証基盤は今後 SSO に置き換える可能性がある

## 決定
セッション ID を発行し、実体は Redis に持つ。JWT は使わない。

## 理由
JWT は有効期限まで失効させられず、即時ログアウトの要件を満たせない。
ブラックリストを持つなら結局ストアが必要で、JWT の利点が消える。

## 結果として受け入れること
- Redis が単一障害点になる → レプリカ構成にする
- 水平分割時にセッションストアの共有が必要になる

README

初めてこのリポジトリを開いた人が、動かせるようになるための文書です。 それ以上のことは書かないでください。

1. これは何か（1〜3行）
2. どう動かすか（コピペで動くコマンド）
3. どう開発するか（テスト・ビルド・よく使うコマンド）
4. どこに何があるか（ディレクトリの説明）
5. 詳しいことはどこを読むか（他ドキュメントへのリンク）

Runbook（手順書）

障害対応や定型作業で、焦っている人が上から順に実行する文書です。 設計ドキュメントとは書き方が根本的に違います。

# API の応答が遅い時

## 判断（30秒で見る）
1. ダッシュボード X を開く → p99 レイテンシを見る
2. 3秒を超えていたら、以下を実行

## 対応
1. Pod の状態を見る
   kubectl get pods -n api
2. Restarts が増えていれば、直前のログを見る
   kubectl logs <pod> -n api --previous
3. OOMKilled なら、レプリカを一時的に増やす
   kubectl scale deploy/api -n api --replicas=6
4. 5分待って回復しなければ、直前のリビジョンに戻す
   kubectl rollout undo deploy/api -n api

## エスカレーション
15分で回復しない場合は #incident に投稿し、@oncall-lead を呼ぶ

判断基準を数字で書くのが要点です。 「重ければ」ではなく「p99 が3秒を超えていたら」と書きます。 深夜3時の人間に判断させないでください。

相談・質問の文面

この教科書の使い方の「詰まった時にどうするか」を、文章の型にしたものです。 これが書けるだけで、新人としての評価が変わります。

【やりたいこと】ユーザー一覧に検索を追加したい
【やったこと】  ListUsers に filter を足して proto を再生成した
【起きたこと】  生成後のビルドで undefined: FilterRequest が出る
【調べたこと】  生成先の .pb.go を見たが FilterRequest が入っていない。
                buf.gen.yaml の paths 設定を疑っている
【聞きたいこと】proto の再生成手順が他にありますか？
【急ぎ度】      今日中に PR を出したい。30分詰まっています

書き方の技術

型より先に、文そのものの品質があります。

結論から書く

悪い: 調査したところ、A の可能性を検討しましたが B ではないかと思われ、
      C も見た結果、おそらく D が原因ではないかと考えています。

良い: 原因は D です。（改行）根拠: ... / 他に見た可能性: A, B, C

読み手は最初の1行で「自分に関係あるか」を判断します。 そこに結論が無いと、読むのをやめます。

曖昧な言葉を消す

「思います」と書きたくなったら、確かめられるかを考えてください。 確かめたなら事実を書けます。確かめていないなら「未確認」と書きます。

1文を短くする

悪い: 今回の変更ではリトライを追加しましたが、その際にタイムアウトも
      調整する必要があったため合わせて修正し、テストも追加しています。

良い: リトライを追加しました。
      合わせてタイムアウトを 3s → 1s に変更しています（リトライ3回で合計3秒に収めるため）。
      テストを2件追加しました。

1文に「が」「ため」で3つ以上つなげたら、切ります。

主語を省略しない

悪い: エラーになったので直しました
良い: CI の lint ジョブがエラーになったので、import の順序を直しました

日本語は主語を省けてしまうため、 誰が・何がを意識して書かないと、読み手が推測することになります。

図を1枚入れる

処理の流れ・システムの構成・状態遷移は、文章より図のほうが速いです。 凝ったツールは要りません。この教科書と同じテキストの図で十分です。

[ブラウザ] --HTTP--> [API] --gRPC--> [検索サービス]
                       |
                       +--------> [Spanner]

実務の落とし穴まとめ

1. 結論が最後にある — 読み手は最初の1行で読むかを決める
2. 「なるべく早く」「だいたい」 — 数字と事実に置き換える
3. 設計ドキュメントを完璧にしてから出す — 7割で早く出す
4. 非ゴールを書かない — 設計レビューが無限に広がる
5. ADR を書き換える — 過去の判断理由が消える。新しく追加する
6. README がコピペで動かない — 新人に試させて直させる
7. 手順書が散文 — 焦っている人は読めない。番号付きの命令形で
8. ドキュメント更新を別タスクにする — 必ず腐る。同じ PR に含める

まとめ

• コードは「どう」しか語らない。なぜ・何を捨てたかは文章にしか残らない
• 最初に読み手（誰が・いつ・何のために読むか）を決める
• 実装に日単位かかるなら設計ドキュメント。特に非ゴールを書く
• 決定は ADR に1件1ファイルで残し、書き換えずに追加する
• README は動かすため、Runbook は実行するため。書き方が違う
• 相談は【やりたいこと / やったこと / 起きたこと / 調べたこと / 聞きたいこと】
• 結論から・数字で・1文を短く・主語を書く
• ドキュメントは腐る。量を減らし、正本を1つにし、同じ PR で直す

公式ドキュメント

迷ったら一次情報に戻ってください。

章末問題

次の章では、そのコードと文章をAI と一緒に書く時に、 何を任せて何を任せないかを扱います。