ドキュメント化とは？意味と進め方5ステップ、エンジニアが書かない理由と続く仕組み

ドキュメント化とは、頭の中やチャットに散らばっている判断・手順・仕様を、後から人が読んで再現できる形に書き起こして共有できる状態にすることです。この記事では、パソコンの「ドキュメント」フォルダやGoogleドキュメントというアプリの話ではなく、システム開発と運用の現場で扱う社内ドキュメントを対象にします。意味と種類、進め方5ステップとテンプレート、書かれない理由、引き継ぎ時の復元手順、置き場所と棚卸しを、Google CloudのDORAの調査データを交えて整理します。

まとめ

ドキュメント化は「文章を増やす活動」ではなく、属人化した判断を、その場にいなかった人が再現できる状態にする活動です。基準は分量ではなく再現性なので、書く量を目標にすると失敗します。

関係は数字で示されています。DORAが2022年の調査で示した分析では、同じ技術プラクティスを導入しても、ドキュメント品質が平均以下のチームと平均以上のチームでは組織パフォーマンスの伸びが大きく分かれました。継続的インテグレーションでは34%対750%、トランクベース開発では36%対1525%です。

進め方は、止まると困る対象から選ぶ、読み手と達成状態を決める、型を決めて1枚目を書く、読み手本人に試してもらって直す、完了の定義とオーナーで工程に組み込む、の5段階です。エンジニアが書かない原因は意識ではなく、見積・評価・古い文書への不信という仕組みの側にあります。

書く対象は絞り、最終確認日とオーナーを文書に持たせ、更新されない文書は棚卸しで捨てます。生成AIに社内情報を読ませる今は、正確で範囲の限定された文書を少数持つことの価値がさらに上がっています。

ドキュメント化の意味と対象範囲

ドキュメント化の意味と、議事録を残すこととの違い

ドキュメント化とは、その場にいた人しか知らない情報を、その場にいなかった人が読んで同じ判断を再現できる形にすることです。議事録やチャットログを保管する行為とは目的が違います。議事録は「何が話されたか」の記録で、ドキュメントは「なぜその結論になったか」と「次に触る人が何をすればよいか」を伝えるために書きます。

Slackを全文検索できても、半年後に別のメンバーが仕様の理由を追えないなら、ドキュメント化はできていません。

システム開発で対象になるドキュメントの種類

対象は役割で切り分けます。開発・保守の関係者向けと、利用者・運用担当者向けでは読み手も更新のきっかけも違います。

この中で後回しにされやすいのが決定記録です。設計書は結果しか書きませんが、「検討したが採用しなかった案」まで残しておくと、数年後の改修で同じ検討をやり直さずに済みます。書式はADR（Architecture Decision Record）とは｜書き方・Markdownテンプレート・design docとの違いにテンプレートを整理しています。設計フェーズ全体の位置づけは基本設計とは？システム開発での位置づけと成果物、要件定義・詳細設計との違い、要件定義書が誰の成果物なのかは要求定義と要件定義の違いとは？責任範囲・成果物・契約の分界点を解説が対応します。

読み手の目的で4つに分けるDiátaxisの考え方

種類表は「何の文書か」で分けたものですが、1本の文書の中身を組み立てるときは「読み手がいま何をしたいか」で分ける方が書きやすくなります。技術文書の書き方の枠組みであるDiátaxis（公式サイトによれば数百のドキュメントプロジェクトで採用）は、読み手の必要を4つに分け、それぞれに対応する文書の形としてチュートリアル、ハウツーガイド、リファレンス、解説を挙げています。

判定に使う問いは2つだけです。中身が「行動（手順）」か「認識（知識）」か、読み手が「学んでいる最中」か「仕事で使っている最中」か。Diátaxisのcompassはこの2問で4つのどれに属するかを決める表になっています。実務で効くのは、手順書に設計背景を長々と混ぜる、READMEにAPIの全パラメータを並べる、といった「形の混在」に気づけることです。

ドキュメント品質と組織成果の関係を示したDORAの調査データ

Google CloudのDORA（DevOps Research and Assessment）は、ドキュメント品質を測定可能な指標として扱っています。DORAのCapabilities「Documentation quality」によると、明確さ・見つけやすさ・信頼性といった属性を8つの指標で評価してモデルに組み込んでいます。

2022年の調査で示されたのは、ドキュメント品質は組織パフォーマンスと直接結びつくだけでなく、他の技術プラクティスの効き目を増幅するという関係です。技術プラクティスを導入したときの組織パフォーマンスの伸びは、ドキュメント品質が平均以下のチームと平均以上のチームで次のように分かれました。

この数値は「ドキュメントを書けば売上が10倍になる」という意味ではありません。同じ技術プラクティスを導入しても、ドキュメント品質が平均以上のチームの方が組織パフォーマンスへの上積みがはるかに大きかった、という差です。量ではなく、明確さ・見つけやすさ・信頼性で測った品質の差である点に注意してください。DORAは2021年レポートの主要知見で質の高い社内ドキュメントを基盤と位置づけ、ソフトウェアデリバリーと運用のパフォーマンス、および他のプラクティスの実装を大きく改善すると述べています。続く2022年のモデルでは、調査対象としたすべての技術プラクティスの実装をドキュメント品質が支えていると報告されました。

ドキュメント化の進め方：着手から定着までの5ステップ

全体を一度に書こうとすると途中で止まるので、次の順で1本ずつ完成させます。

ステップ1：止まると困る業務からの対象選定

最初の1本は、担当者が不在になったら業務やシステムが止まるものから選びます。開発現場なら、本番リリースの手順、障害時の復旧手順、特定の人しか触れない設定です。判断材料は「その人が明日から2週間休んだら何が止まるか」の1問で足ります。業務全般の属人化の洗い出し方は属人化とは？原因・リスクと脱属人化を進める仕組み化・標準化の実務で整理しています。

ステップ2：読み手と読了後の達成状態の定義

書く前に「誰が、どの状況で読み、読み終えたら何ができているか」を1文で書きます。「参画3日目のメンバーが、この文書だけでローカル環境を起動できる」のように、達成状態を確かめられる形にするのがコツです。この1文が書けない文書は読み手が決まっていないので、まだ書き始める段階ではありません。前節のDiátaxisの4つの形のどれに当たるかも、ここで決まります。

ステップ3：型の決定と1枚目の作成

チームで型を1つ決め、先頭に管理用の情報を置きます。最終確認日とオーナーは、後の棚卸しで古い文書を洗い出すために要ります。

# 本番リリース手順（決済API）

- 目的：参画1か月以内の開発者が、この手順だけで本番リリースとロールバックを実行できる
- 読み手：決済チームの開発者
- オーナー：山田（決済チーム）
- 最終確認日：2026-10-26（確認者：佐藤）
- 関連：ADR-012 デプロイ方式の選定

## 前提
- リリース権限（deploy-prod ロール）が付与されていること

## 手順
1. リリースブランチのCIが全て成功していることを確認する
2. ...

## 失敗したとき
- ロールバック手順：...
- 連絡先：#payment-incident

本文は箇条書きの手順と、手順を誤ったときの戻し方を優先します。設計の背景を書きたくなったら、手順書には入れずADRなど別の文書に分けてリンクします。最初から完璧を目指さず、手順が最後まで通る状態を下書きの完成とします。

ステップ4：読み手本人による試行と詰まった箇所の修正

書いた本人のレビューでは抜けに気づけません。ステップ2で決めた読み手に、文書だけを頼りに実際に作業してもらい、質問が出た箇所・手が止まった箇所を記録して、そこだけを直します。記録するのは、質問の数と、作業を終えるまでにかかった時間の2つです。2人目の読み手で質問が出なくなった時点を文書としての完成とします。

ステップ5：完了の定義とオーナーによる工程への組み込み

更新は個人の善意から工程に移します。チケットの完了条件に「関連ドキュメントの更新」を含め、更新が無いままのマージを認めません。あわせて文書ごとにオーナーを1人決めます。「チーム全員で管理」は誰も管理しないことと同義です。オーナーは自分で全部書く人ではなく、内容が古くなったときに更新を差配する責任者として置きます。

エンジニアがドキュメントを書かない構造的な理由

「意識が低いから」で片付けると対策を誤ります。書かれない現場には、書けない構造が揃っています。

工数に計上されない書き仕事

最初に潰すべきは工数の問題です。見積の内訳が設計・実装・テストで構成され、ドキュメント作成の行が無い状態でスケジュールが確定すると、書く時間はどこにも存在しません。評価されない不可視の作業は、リリース直前の圧縮で真っ先に消えます。

対策は見積の形式を変えることです。「実装 5人日」ではなく「実装 5人日＋設計判断の記録 0.5人日」と分けて積みます。書く時間を独立した行として見積に載せ、スケジュールの圧縮で消えない形にします。

評価に反映されない成果物

2つ目は評価制度です。コミット数やクローズしたチケット数は可視化されるのに、参画メンバーの立ち上がりを3日短縮した文書は誰の成果にもなりません。合理的に行動するエンジニアほど、評価される作業に時間を寄せます。

評価面談の観点に「他者の作業時間を減らした貢献」を明示的に加え、レビューで言及される文書を成果として扱います。DORAのDocumentation qualityのページも、文書づくりの協力者としてテクニカルライターや「documentation champions」（文書化の推進役）を挙げています。推進役を役割として明示し、その働きを評価に載せるのが現実的な形です。制度を変えられない場合でも、振り返りで「この文書に助けられた」を具体名で共有するだけでも動機づけになります。

古い記述が信用を失わせる悪循環

3つ目が最も厄介です。一度でも「書いてある通りにやったら動かなかった」経験をすると、そのドキュメント群全体が信用を失います。読まれない文書は更新もされず、さらに古くなります。DORAも品質を測る指標に信頼性（reliability）を含めています。正確さを欠いた文書は、読み手にとって存在しないのと同じ扱いになります。

この悪循環は、量を増やすより信用できない文書を先に消す方が断てます。最終確認から1年以上が経ち、内容の正しさを誰も保証できない手順書は、残すより削除して「無い」と明示した方が安全です。誤った手順は、無い手順より害が大きいからです。

ドキュメントがないシステムを引き継ぐときの復元手順

最初に復元する4種類の文書

既存システムを引き継いだが設計書が一枚も残っていない、という状況では、全体を復元しようとすると途中で止まります。着手順を固定します。

1. システム構成図（何がどこで動き、何と通信しているか）
2. 監視とアラートの一覧（何が鳴り、誰に届くか）
3. 復旧手順（落ちたとき誰が何をするか）
4. 変更手順（リリースとロールバックの流れ）

4つとも止まったときに必要になる情報です。仕様の詳細は時間をかければコードから追えますが、深夜の障害時にサーバの場所と再起動順は推測できません。機能仕様書の復元は後回しで構いません。

コードから機械的に起こせる部分と、人にしか書けない部分

復元を全部人力でやる必要はありません。APIの入出力仕様はOpenAPI定義やアノテーションから、APIリファレンスはコメントやdocstringからJavadocやDoxygenで生成でき、データベースの構造は既存スキーマからER図を起こせます。テーブル定義や画面一覧のような「現状の写し」は自動生成に寄せて構いません。生成AIでコードを読ませて仕様書の下書きを作る手順と限界は生成AIモダナイゼーションの実装手順｜コード解読・仕様復元・テスト生成と限界にまとめています。

人にしか書けないのは、現状から読み取れない情報です。なぜこのテーブルだけ正規化されていないのか、なぜこのバッチは毎月1日ではなく2日に動くのか。当時の関係者が在籍しているうちに背景を聞き取って残すことが、引き継ぎで後回しにできない作業です。設計判断を残す様式はデザインドック（Design Doc）とは？書き方とテンプレート、書くべき場面とAIでの下書きのテンプレートが使えます。

書くものと書かないものを分ける判断基準

すべてを文書化しようとする方針は、ドキュメントを書かない方針と同じくらい失敗します。更新されない文書が増えるほど、正しい文書を探す時間が伸び、全体の信用が下がるからです。書くべきかどうかは、次の問いに1つでも当てはまるかで判断できます。

• 影響範囲が複数のコンポーネントやチームにまたがる
• 後から「なぜこうしたのか」と問われる可能性がある
• チーム内で意見が割れ、トレードオフを取った
• 手順を誤ると本番データやサービスに影響が出る

逆に、コードとテストを読めば1分で分かる内容、口頭30秒の確認で済む内容、半年後には存在しない一時的な回避策は、書かない判断が正解です。とくに関数の引数をコードの外で書き直した文書は、コードが変わった瞬間に嘘になります。同じ情報が2箇所にあると、片方が必ず腐ります。

この基準を採用すべきでない場面もあります。医療機器ソフトウェアのIEC 62304（現行は2006年版に2015年の追補1を統合したEdition 1.1）は、ソフトウェア安全クラスごとに実施すべきアクティビティとその文書化を定めており、読まれるかどうかに関係なく規格適合のための記録が求められます。品質マネジメントのISO 9001は2026年9月16日に2026年版が発行されて2015年版を置き換えましたが、引き続き文書化した情報の管理を求める規格です（運用の設計はISO9001の文書管理とは｜文書化要求(版管理・承認・改訂履歴)を満たす仕組みと運用設計で扱っています）。こうした領域では「読むための文書」と「証跡としての文書」を分けて管理してください。証跡を読み物の代わりに使うと、どちらの目的も果たせなくなります。

システム開発のドキュメント管理：置き場所の選び方と棚卸し

置き場所の3類型と、更新のきっかけによる選び方

設計書は共有ドライブ、手順書はWiki、決定記録はチケットのコメントと散っていると、どれが最新か判断できません。置き場所はプロジェクト単位で決めます。選び方の軸はツールの機能差ではなく、文書がどのきっかけで更新されるかです。

コードと同時に変わる文書は、コードと同じリポジトリに置くのが最も腐りにくい選択です。Write the Docsの解説は、Docs as Codeを課題管理・Git・プレーンテキストのマークアップ・コードレビュー・自動テストといったコードと同じ道具でドキュメントを書く考え方と説明しています。プルリクエストで実装と文書の差分を同時にレビューでき、ステップ5の完了の定義と噛み合います。Markdownから社外向けのドキュメントサイトを作る場合はDocusaurusとは：ドキュメントサイトの構築手順とバージョン管理・多言語・検索の設定【3.10対応】が参考になります。

一方、発注者や業務部門も編集する運用手順や、承認と版の管理が要る納品文書をGitに寄せると、触れる人が限られて更新が止まります。承認フローや改訂履歴、閲覧権限まで含めて管理したいなら、Wikiの延長ではなく文書管理システムの開発を検討する段階です。社内の知見を蓄積するナレッジ管理と、版と承認を管理する文書管理の違いはナレッジマネジメントと文書管理の違い｜目的・評価指標と統合設計の判断基準で整理しています。

更新されない文書を捨てる棚卸しの仕組み

増やす仕組みと同時に、減らす仕組みが要ります。ステップ3の型で文書の先頭に置いた最終確認日を使い、最終確認から180日を過ぎたものを棚卸し対象として洗い出します。1年を超えて正しさを保証する人がいない手順書は、この棚卸しで削除に振り分けます。棚卸しでは3択にします。内容を更新する、削除する、あるいは「この内容は保証しない」と明記して参考扱いに落とすかです。

判断を保留にしたまま残す選択肢は用意しません。保留を許すと、判断されない文書だけが蓄積し、結局は誰も信じない文書群に戻ります。

AI開発時代にドキュメントが担う新しい役割

AIを増幅器と位置づけたDORA 2025の結論

いまは読者が人間だけではありません。DORAの2025年レポートは「State of AI-assisted Software Development」と題され、AIの主な役割は増幅器であり、組織が既に持っている強みと弱みを拡大するとまとめています。ツールを入れれば横並びで生産性が上がるわけではありません。

AIに社内情報を接続するときの前提条件

DORAがAIの効果を増幅する7つの能力（AI Capabilities Model）の1つに挙げているのが、AIから参照できる社内情報です。DORAのCapabilities「AI-accessible internal data」は、AIツールが社内データに直接アクセスできるとAI導入の効果が増幅され、個人の有効性とコード品質に対する統計的に有意な乗数として働くと説明しています。必要な文脈だけを渡す方式としては、RAGとMCPサーバーの2つのパターンが現れつつあると紹介されています。

同じ解説は「存在しない情報にAIを接続することはできないし、誤った情報に接続すべきでもない」と述べ、高品質なドキュメントがAI導入の主要な推進要因だと位置づけています。社内文書が無ければAIは汎用的な回答しか返せず、古ければ誤った前提のコードを速く量産します。落とし穴として挙げられているのも、社内データの品質が低いこと、廃止済みのパターンを学習してしまうこと、大量の文書を無差別に渡して文脈が薄まること、特権的な接続や共有サービスアカウントで接続して最小権限が守られないことの4点です。

AIに読ませる前提に立つと、量を投げ込むほど精度が下がります。正確で範囲の限定された文書を少数持つことが、人にもAIにも誤答を減らす最短の手段です。ドキュメント化を先送りしてきた組織では、AI導入はこれまでの差を縮めず、むしろ広げます。

よくある質問

ドキュメント化とは簡単に言うと何ですか？

人の頭の中にある判断や手順を、別の人が読んで同じことを再現できる文書にすることです。チャットや議事録の保存だけでは足りず、「なぜそうしたか」が読み取れることが条件です。

ドキュメント化と文書化・ドキュメンテーション・ドキュメント作成に違いはありますか？

日本語ではほぼ同じ意味で使われます。強いて分けるなら、ドキュメント作成や文書化は1本の文書を作る行為、ドキュメンテーションは書式の統一や公開・更新までを含む継続的な取り組みを指す場面が多い言葉です。呼び方より、判断の背景まで書かれているかが基準です。

ドキュメントはどこまで細かく書くべきですか？

想定した読み手が、その文書だけで作業を最後まで再現できる粒度が目安です。読み手に試してもらって質問が出た箇所だけを足し、コードを読めば分かる内容や口頭で済む確認は書きません。細かさを揃えるより、読み手と達成状態を先に決める方が粒度は安定します。

ドキュメント作成はエンジニアの仕事ですか？

設計判断の背景や実装上の制約は書いた本人にしか正確に説明できないため、エンジニアが担う領域です。ただし見積と評価に載らない限り定着しません。用語統一や表記の整形はテクニカルライターに任せる分担も選べます。

ドキュメント作成能力はどう高めればよいですか？

読み手と達成状態を決めてから書き、実際にその読み手に試してもらって詰まった箇所を直す、という往復を繰り返すのが最短です。表記の判断に迷う時間を減らすには、Google developer documentation style guideのような公開された表記基準を1つ採用し、チームの基準として固定する方法があります。

関連記事

• デザインドック（Design Doc）とは？書き方とテンプレート、書くべき場面とAIでの下書き
• ADR（Architecture Decision Record）とは｜書き方・Markdownテンプレート・design docとの違い
• 属人化とは？原因・リスクと脱属人化を進める仕組み化・標準化の実務
• ナレッジマネジメントと文書管理の違い｜目的・評価指標と統合設計の判断基準
• 基本設計とは？システム開発での位置づけと成果物、要件定義・詳細設計との違い