はじめに
「ドキュメント、書いてますか？」
この質問に自信を持って「はい」と答えられるエンジニアは、
意外と少ないのではないでしょうか。
私自身、データエンジニアとしてチーム開発に携わる中で、
ドキュメントの重要性を痛感してきました。コードは書くけどドキュメントは後回し。
気づけば「あの処理って何してるんだっけ？」という質問が飛び交い、
同じ説明を何度も繰り返す日々——。
この記事は、下記のテーマで書いています
「ドキュメントを書く」という地味な行為が、なぜチームを変え、そして書いた本人を最も成長させるのか。その理由を、できるだけ具体的にお伝えします。
なぜドキュメントは書かれないのか
「コードが最新のドキュメントだ」という幻想
エンジニアの間でよく聞くフレーズがあります。
「コードを読めばわかる」
「コードが最新のドキュメントだ」
たしかに、コードは嘘をつきません。動いているコードこそが「今の仕様」であることは事実です。しかし、コードが教えてくれるのは What（何をしているか） だけです。
- Why（なぜこの設計にしたのか）
- Context（どんな制約や事情があったのか）
- History（過去にどんな選択肢を検討して却下したのか）
これらはコードからは読み取れません。新人がソースコードを前にして途方に暮れるのは、能力の問題ではなく、この Why と Context が欠落しているから です。
書かないことで発生する"見えないコスト"
ドキュメントを書かないことは、短期的には時間の節約に見えます。しかし実際には、以下のような「見えないコスト」がじわじわとチームを蝕みます。
| コストの種類 | 具体的な症状 |
|---|---|
| 属人化 | 特定の人しか触れないコードが増える |
| オンボーディング遅延 | 新人が戦力化するまでに数ヶ月かかる |
| 同じ質問の繰り返し | 先輩の作業が毎日中断される |
| 意思決定の手戻り | 過去の経緯を知らず、同じ失敗を繰り返す |
「ドキュメントを書く30分」を惜しんだ結果、「説明する30分 × 聞きに来る人数 × 発生回数」という膨大な時間を失っているのです。
生成AI時代でも「人間が書くべきドキュメント」がある
AIが得意な領域
2024〜2026年にかけて、生成AIのコード支援能力は飛躍的に向上しました。たとえば以下のようなドキュメント生成は、AIの力を借りることで大幅に効率化できます。
- API仕様書の雛形生成
- コードコメントの自動補完
- README テンプレートの作成
- 既存コードからのdocstring生成
GitHub Copilot や Claude などを使えば、関数の説明文やパラメータの解説は、かなりの精度で自動生成できます。こうした「定型的なドキュメント」はAIに任せてしまいましょう。
AIでは書けない領域
一方で、AIにはどうしても書けないドキュメントがあります。
-
社内固有のドメイン知識：「このテーブルの
flag_aは、○○クライアントの要望で2023年に追加された」 - 意思決定の背景：「Snowflakeではなく BigQuery を選定したのは、既存のGCPインフラとの親和性とコスト試算の結果」
- 業界特有の慣習：「小売業のPOSデータでは、返品は翌日マイナス計上されるため、日次集計と月次集計で差異が出る」
- 暗黙の運用ルール：「このバッチは月初3営業日以内に実行しないと、経理の締め処理に間に合わない」
これらは、そのチーム・その業界にいる 人間の頭の中にしか存在しない情報 です。AIに「社内のデータパイプラインの設計思想を書いて」と指示しても、的外れな一般論しか返ってきません。
つまり、AIの活用が進むほど、人間にしか書けないドキュメントの価値は相対的に上がるのです。
ドキュメントがチームにもたらす3つの効果
1. 新人がソースコードを「読める」ようになる
新人にとって最も辛いのは、「何千行もあるコードのどこから読めばいいかわからない」状態です。
たとえば、以下のようなシンプルなドキュメントがあるだけで、状況は劇的に変わります。
# データパイプライン概要
## 処理の流れ
1. S3バケットにCSVが日次で配置される（毎朝6:00）
2. Bronzeレイヤーで生データをそのまま取り込む（COPY INTO）
3. Silverレイヤーでクレンジング・型変換を実施
4. Goldレイヤーで集計テーブルを生成 → ダッシュボードに連携
## 注意点
- 毎月1日はデータフォーマットが変わることがある（クライアント都合）
- Silver→Gold変換のバッチが失敗した場合、Slackの #data-alert に通知が飛ぶ
これだけで、新人は「全体像」と「最初に見るべきコード」を把握できます。コードリーディングのスタート地点が明確になるのです。
2. 質問の質が上がる（先輩の時間を奪わない）
ドキュメントがない環境では、新人の質問はどうしてもこうなりがちです。
「このコード、何やってるんですか？」
これは先輩にとって最もコストが高い質問です。ゼロから説明しなければならず、15分〜30分が簡単に消えます。
一方、ドキュメントがある環境では質問の粒度が変わります。
「パイプライン概要ドキュメントを読んで、Silver→Gold変換の部分は理解できました。ただ、
transform_gold.pyの120行目でflag_aでフィルタしている理由がわかりません。これはどういう業務要件ですか？」
この質問なら、先輩は1〜2分で的確に答えられます。ドキュメントは 「質問の前提知識」 を底上げし、コミュニケーションの効率を飛躍的に高めるのです。
3. 書いた本人の理解が深まる（ラバーダッキング効果）
実は、ドキュメントの最大の受益者は 読む人ではなく書いた本人 です。
「ラバーダッキング」1という言葉をご存知でしょうか。ゴム製のアヒルに向かって問題を説明するだけで、解決策が浮かぶという現象です。ドキュメントを書く行為は、まさにこれと同じ効果があります。
- 「この処理を説明しようとしたけど、自分でもなぜこう書いたかわからない」→ 設計の曖昧さに気づける
- 「前提条件を書き出したら、考慮漏れが見つかった」→ バグの予防になる
- 「人に伝わる言葉で整理したら、もっとシンプルな実装を思いついた」→ リファクタリングのきっかけになる
ドキュメントを書くことは、自分の頭の中を棚卸しする行為です。入社半年の新人であっても、自分が担当した機能のドキュメントを書けば、その領域では誰よりも詳しくなれます。それが「頼られるエンジニア」への最短ルートです。
「完璧じゃなくていい」から始めるドキュメント習慣
書く場所・タイミングのTips
| タイミング | 書く内容 | 効果 |
|---|---|---|
| PR（Pull Request）作成時 | 変更の背景と影響範囲 | レビューの質が向上 |
| 障害対応後 | 原因・対処・再発防止策 | 同じ障害の対応時間を短縮 |
| スプリント終了時 | 今スプリントで学んだこと | ナレッジの蓄積 |
| 新しいツール導入時 | セットアップ手順とハマりポイント | 次の人のセットアップ時間を大幅短縮 |
おすすめは PRのDescription に書く習慣をつけることです。コードレビューのついでにドキュメントレビューもでき、「書く場所に迷う」問題を解消できます。
レビュー文化とセットで回す
ドキュメントを書いても、レビューされなければ品質は上がりません。コードレビューと同じように、ドキュメントにもレビューの仕組みを取り入れましょう。
- PRにドキュメント更新を含めることをチームルールにする
- 「ドキュメントの更新がないPRはマージしない」くらいの意識を持つ
- 新人が書いたドキュメントを先輩がレビューし、フィードバックする
この循環が回り始めると、チーム全体の知識レベルが底上げされ、属人化が徐々に解消されていきます。
まとめ
この記事のポイントを振り返ります。
- ドキュメントが書かれない理由は「面倒」だけでなく、「コードが最新のドキュメント」という誤解もある
- AIが進化しても、社内のドメイン知識・意思決定の背景・業界慣習は人間にしか書けない
- ドキュメントは新人のコードリーディングを助け、質問の質を上げ、書いた本人の理解を深める
- 完璧でなくていい。まず1つ、自分が担当した機能のドキュメントを書いてみよう
最初の1本を書くのが一番ハードルが高いです。でも、書いてみると気づくはずです。「これ、一番助かったのは自分だった」と。
入社半年で"頼られるエンジニア"になるために。今日、1つドキュメントを書いてみませんか？
-
ラバーダッキング（Rubber Duck Debugging）：問題をゴムのアヒルに声に出して説明することで、自力で解決策に気づけるというデバッグ手法。実際には人に説明する、文章に書き出すなど、思考を言語化する行為全般に同じ効果がある。 ↩