ドキュメンテーション
ドキュメンテーションとは
ドキュメンテーションは、ソフトウェアに関する知識を文書として残し、伝わる状態に保つ活動です。コードは「どう動くか」を語りますが、「なぜそう作ったか」「どう使うか」はコードだけでは伝わりません。その隙間を埋めるのが文書の役割です。
読み手は同僚だけではありません。数か月後の自分が最大の読者です。「当時は自明だったのに思い出せない」を防ぐことが、文書を書く一番の動機になります。
開発現場の代表的なドキュメント
| 種類 | 内容 |
|---|---|
| README | プロジェクトの概要・セットアップ手順・使い方。最初に読まれる玄関 |
| 設計書・仕様書 | システムの構造や振る舞いの定義。[[要件定義]] の成果物もここに含まれる |
| ADR(Architecture Decision Record) | 設計判断の「なぜ」と却下した代替案を記録する |
| API ドキュメント | エンドポイントやパラメータの仕様。OpenAPI などで自動生成も可能 |
| 運用手順書(Runbook) | 障害対応やリリース作業の手順 |
良いドキュメントの原則
- コードの近くに置く — リポジトリ内の Markdown なら [[Git]] でコードと一緒にバージョン管理でき、[[コードレビュー]] の対象にもなります
- 「なぜ」を書く — 「何をしたか」はコードや差分で分かります。判断の理由と捨てた選択肢こそ文書に残す価値があります
- 更新されない文書は害になる — 古い手順書は読者を誤らせます。書く量を絞り、変更時に一緒に直せる範囲に保ちます
- 読者を決めて書く — 新規参加者向けか、運用者向けかで書くべき内容は変わります
初学者向けポイント
- まず README から書く練習をしましょう。「初めて見た人がセットアップして動かせるか」が良い README の基準です
- 完璧な文書を目指すより、陳腐化しにくい構造(概要と「なぜ」を中心に、変わりやすい詳細はコードに任せる)を意識しましょう
- 障害調査や議論の経緯は [[チケット管理]] に残ることも多く、文書とチケットの役割分担を意識すると整理しやすくなります
- コード内のコメントも小さなドキュメントです。「何をしているか」より「なぜこうしているか」を書くと価値が出ます
関連技術とのつながり
- [[Git]] — 文書をコードと一緒にバージョン管理する土台
- [[コードレビュー]] — リポジトリ内の文書はレビューの対象にできる
- [[要件定義]] — 開発の出発点となる文書を作る工程
- [[チケット管理]] — 経緯や議論を残す場所として文書と役割分担する
- [[クリーンコード]] — コード内コメントに「なぜ」を書く原則は、文書化の考え方と共通する
Q: 本文で「文書に残す価値が最も高い」とされている情報はどれ?
- [ ] コードを読めば分かる処理の手順
- [x] 設計判断の理由と却下した代替案
- [ ] 毎日変わる作業の進捗状況
解説: 「何をしたか」はコードで分かりますが、「なぜそうしたか」はコードに残らないため文書化の価値が高い情報です。
Q: 設計判断の「なぜ」を記録する文書の名前はどれ?
- [ ] README
- [ ] Runbook
- [x] ADR(Architecture Decision Record)
解説: ADR は設計判断とその理由・代替案を記録する文書です。README は玄関、Runbook は運用手順書です。
Q: ドキュメントをリポジトリ内に置く利点として本文で挙げられているのはどれ?
- [x] コードと一緒にバージョン管理でき、レビューの対象にもなる
- [ ] 文書が自動的に多言語翻訳される
- [ ] 文書が絶対に古くならなくなる
解説: リポジトリ内の Markdown は Git で管理でき、コードレビューのフローに乗せられます。陳腐化自体は防げないため更新の工夫は別途必要です。