documentation-strategy

ドキュメント戦略

何を、どこに、誰が記載し、どうやって最新の状態を保つかを決めます。技術スタックに依存しません。社内チームのドキュメント、製品ドキュメント、運用手順書、README、ナレッジベースに適用できます。

---

使用する場面

• 新しいチームや製品のドキュメントを整備するとき
• 既存のドキュメントを監査するとき
• 古くなったドキュメントや散在しているドキュメントを整理するとき
• ドキュメントのツールやプラットフォームを選ぶとき
• 何を記載し、何を記載しないかを定義するとき
• メンテナンスの頻度を決めるとき
• テクニカルライティングの作業範囲を定めるとき
• オンボーディング用ドキュメントを設計するとき（team-onboarding-playbook と併用してください）

使用しない場面

• 単一のドキュメントの本文を書くとき（content-and-copy を使用してください）
• 顧客向けナレッジベースの文章を書くとき（content-strategy を使用してください）
• コードコメントやインラインドキュメントを書くとき（code-review-web が対象です）
• 単発のブログ記事や記事を書くとき（content-and-copy を使用してください）

---

必要な入力

• 対象読者（社内、社外、顧客、開発者、経営幹部）
• 既存ドキュメントとその状態（場所、内容、最終更新日）
• チームの規模と成長の見通し
• ドキュメント作成につながる業務の種類（エンジニアリング、製品、運用、サポート）
• 現在使用しているツール

---

フレームワーク：ドキュメントの4つのカテゴリ

ドキュメントのカテゴリごとに目的は異なります。これらを混同すると、ドキュメントの質が低下します。

カテゴリ1：リファレンス

物事が何であるかを記述します。必要に応じて参照します。

例：API リファレンス、設定オプション、用語集、アーキテクチャ図、連絡先リスト、意思決定ログの項目。

特性：

• 網羅的である
• 事実確認され、正確な状態が保たれている
• 検索できる
• 構成が安定している（リンクが切れない）
• 該当する場合はバージョンを考慮している

カテゴリ2：ハウツー

特定のタスクの実行方法を記述します。手順を説明します。

例：「ステージング環境にデプロイする」「パスワードをリセットする」「新しい契約社員をオンボーディングする」「バックアップの復元訓練を実施する」。

特性：

• 手順が段階的に示されている
• 作成者以外の人が試している
• 前提条件が含まれている
• トラブルシューティングが含まれている
• 対象システムのバージョンに合わせて管理されている

カテゴリ3：説明

物事がそのようになっている理由を記述します。概念を説明します。

例：アーキテクチャの根拠、設計決定記録（ADR）、戦略ドキュメント、ビジョンドキュメント。

特性：

• 叙述形式である
• 背景（理由）を記録している
• 多くの場合、過去の経緯を扱う（なぜこのように構築したのか）
• 根拠へのリンクがある

カテゴリ4：チュートリアル

学習を目的とし、初心者を一人前の利用者へと導きます。

例：「コードベースの使い始め方」「初めてのデプロイ」、オンボーディングの手順。

特性：

• 簡単な内容から複雑な内容へと順序立てている
• 実践的である
• 対象範囲について事前知識を前提としない
• 明確な完了条件がある

（この4分類は、テクニカルライティングで広く知られる Diátaxis フレームワークです。覚えておきましょう。）

---

フレームワーク：ドキュメントの5つの階層

ドキュメントは、重要度の異なるさまざまな対象読者に向けて作成されます。

階層1：顧客向け

公開ドキュメント、顧客向けナレッジベース、API リファレンスなど。公開範囲が広く、変更頻度は低めです。

基準：

• 編集レビューを行う
• バージョン管理する
• 明確なオーナーを定める
• 最新状態を保つための高い基準を設ける
• リリースと連動させる

階層2：チーム横断／共有

共有 API、共通サービス、全社プロセスなど、複数のチームが利用するドキュメントです。

基準：

• チーム横断のオーナーシップを明確にする
• 変更時の更新義務を定める
• 最新状態を保つための中〜高の基準を設ける

階層3：チーム内

オーナーであるチーム向けのドキュメントです。チームの作業方法、運用手順書、意思決定などが含まれます。

基準：

• チームがオーナーとなり、チームでメンテナンスする
• 最新状態を保つための中程度の基準を設ける
• 新たに参加する人に役立つ内容にする

階層4：個人用メモ

メモ、下書き、作業中の内容です。他者向けではありません。

基準：

• メンテナンスの負担を低くする
• 公式ドキュメントからリンクしない
• 価値がある場合は上位の階層へ移す

階層5：自動生成

コードから生成されるドキュメントです。コメントやスキーマなどから生成された API リファレンスが該当します。

基準：

• 生成を自動化し、CI で実行する
• 信頼できる唯一の情報源はコードとする
• 最新状態ではなく、使いやすさをレビューする（最新状態は自動で保たれます）

階層分けが重要なのは、メンテナンスの基準が異なるためです。チーム内ドキュメントに顧客向けの基準を求めるのは、無駄が多く持続できません。

---

ワークフロー

ステップ 1：現状を監査する

• どのようなドキュメントがありますか？
• どこにありますか？（多くの場合、あちこちに散在しています）
• それぞれの所有者は誰ですか？
• どのくらい新しいですか？
• 実際に使われていますか？（測定可能であれば、ページビューや参照元を確認します）

監査をすると、目を見張ることがよくあります。ほとんどのチームは、思っている以上のドキュメントを、思っている以上に多くの場所に持っています。

ステップ 2：分類して階層分けする

ドキュメントごとに、次の項目を設定します。

• カテゴリ（リファレンス／ハウツー／解説／チュートリアル）
• 階層（顧客向け／共有／チーム／個人メモ／自動生成）

複数のカテゴリにまたがるドキュメントもあります。主要なカテゴリを記録してください。

ステップ 3：不足しているものを特定する

チームに必要なのに、存在しないドキュメントは何ですか？

よくある不足例：

• 「X は実際にどう動くのか？」に答えるものがない
• 最近オンボーディングを担当した人がいない役割のオンボーディング資料
• （まだ）一度も壊れたことのないシステムのランブック
• 「なぜこの方法で進めているのか」という判断の根拠

何を文書化してほしいか、メンバーに尋ねてください。本人たちが知っています。

ステップ 4：不要なものを特定する

次のようなドキュメントです。

• 古くなっていて、更新もされていない
• 複数の場所に重複している（正本を 1 つ決め、ほかはリダイレクトするか削除します）
• すでに存在しないものについて書かれている
• ずっと前に放棄された下書き

削除するか、アーカイブしてください。古いドキュメントは、存在しないドキュメントよりも有害です（読んだ人が信頼してしまう可能性があります）。

ステップ 5：保管場所を決める

ドキュメントの保管場所は、メンテナンスされるかどうかに影響します。

よくある保管場所：

• コードリポジトリ（markdown）： コードと密接に関連するドキュメント（README、ADR、サービスのランブックなど）
• Wiki／Notion／Confluence： チーム横断の情報やチーム内向けの情報
• ドキュメントサイト（Docusaurus、Mintlify、カスタム）： 顧客向けの情報
• チケット／意思決定ログ： 一時的な記録

保管場所を 1 つに絞ることを目指すのではなく、「この種類のドキュメントはどこにあるか？」に明確に答えられる状態を目指してください。

ステップ 6：所有者を決める

すべてのドキュメントに所有者がいます。所有者がいないと、ドキュメントは古くなります。

所有者は、次のいずれかです。

• チーム
• 役割（オンコール担当のローテーション、PM、EM）
• バックアップ担当者を含む個人

所有者が明確でない場合、そのドキュメントは存在する必要がないのかもしれません。

ステップ 7：メンテナンスの頻度を決める

階層ごとの頻度：

階層	レビュー頻度
顧客向け	リリースごと、加えて四半期ごと
チーム横断	四半期ごと
チーム内向け	四半期ごと
個人メモ	なし
自動生成	変更のたび

メンテナンスには、次の作業が含まれます。

• 正確性を確認する
• システムの変更に合わせて更新する
• 関連性がなくなったものをアーカイブする
• ユーザーからのフィードバックに対応する

ステップ 8：ドキュメントの更新を仕事に組み込む

ドキュメント作成は独立したプロジェクトではありません。ドキュメントを生み出す仕事の一部です。

• 新機能：ドキュメント作成も機能の一部
• 新しいプロセス：ドキュメント作成も展開の一部
• 意思決定：ADR または意思決定ログのエントリを記録
• バグの事後分析：ランブックを更新
• 新入社員：本人の経験をもとにオンボーディング資料を更新

ドキュメントなしで機能をリリースするチームは、自分たちが持っていると思っている以上に、持っているものが少ないのです。

ステップ 9：ドキュメントを見つけやすくする

どれほど優れたドキュメントでも、見つけてもらえなければ役に立ちません。

• 実際に機能する検索（ほとんどのプラットフォームにありますが、性能には差があります）
• 主要なトピックの索引ページ
• 関連するドキュメント間の相互リンク
• よく使われる別の言い回しで検索できる別名
• 最もよく使われるドキュメントのピン留め

ステップ 10：測定する

測定できる項目はプラットフォームによって異なります。

• ページビュー
• 検索クエリ（結果が 0 件だったクエリも含む）
• 「役に立ちましたか？」というフィードバック
• ページの滞在時間
• 参照元のパターン

社内ドキュメントの場合、定性的な指標のほうが役立つことがよくあります。同じ質問が何度も繰り返されていますか？そうであれば、ドキュメントは役割を果たせていません（存在しない、見つからない、または分かりにくいのいずれかです）。

---

具体的なパターン

プロジェクトごとの README

すべてのコードリポジトリに、次の質問に答える README を用意します。

• これは何ですか？
• どうすれば実行できますか？
• どうすれば貢献できますか？
• 詳細情報はどこで見つかりますか？

それぞれ 5 文程度で十分なことがよくあります。長さが目標ではありません。「README」という名前が約束する役割を果たすことが大切です。

ADR（アーキテクチャ決定記録）

重要な意思決定ごとに作成します。

# ADR-NNN: [Title]

Status: [Proposed / Accepted / Deprecated / Superseded]
Date: [Date]

## Context
[What's the situation? What forces are at play?]

## Decision
[What was decided?]

## Consequences
[What happens because of this decision? Both good and bad.]

ADR は蓄積されていきます。「なぜこの方法で進めているのか」を説明するレイヤーになります。

ランブック

システムごとに、以下を記載します。

• システムの概要
• アクセス方法
• 一般的な操作（コマンドを含む）
• よくある障害
• バックアップからの復元手順
• エスカレーション先の連絡先

ランブックの標準については、incident-response と backup-and-disaster-recovery を参照してください。

オンボーディングの道筋

役割ごとに、以下を記載します。

• 1日目
• 1週目
• 1か月目
• 90日目

team-onboarding-playbook を参照してください。

意思決定ログ

ADRの簡易版です。日付、決定事項、決定者、その理由を記録します。形式ばらずに記録を残せます。

用語集

チームやプロダクトで特定の意味を持つ用語をまとめます。混乱を減らし、AI ツールの学習にも役立ちます（詳しくは後述）。

---

ツール

ツールよりも、規律のほうが重要です。とはいえ、以下を参考にしてください。

ツールのカテゴリ	例	最適な用途
Wiki	Notion, Confluence, GitBook	チーム横断、社内向け
コード内の Markdown	GitHub, GitLab, Bitbucket	README、ADR、技術文書
ドキュメントサイト	Docusaurus, Mintlify, ReadMe	顧客向け、公開ドキュメント
社内サイト	MkDocs, custom	チーム固有のパターン

検討事項：

• 検索の品質（検索の質が低いと、すべてが使いにくくなります）
• エディターの品質（使いにくいエディターでは、誰も書きません）
• バージョン管理（履歴を確認できますか？）
• 権限（適切な人が読み書きできますか？）
• API と連携（自動化に必要です）
• チーム規模に応じたコスト

小規模なチームなら、Wiki ツールは1つで十分です。規模が大きい場合は、ツールを階層化しましょう。

---

AI 関連の注意事項

LLMやAI アシスタントがドキュメントを読む機会が増えています。以下の点を考慮してください。

• 明確で一貫した構成は、人にもAIにも役立ちます
• 用語集は、人にもAIにも役立ちます
• ファイル単位のメタデータ（フロントマター）は、ツールに役立ちます
• 公開ドキュメントはAIクローラーに読まれる可能性があります。必要に応じて llms.txt を検討してください
• AIが生成した草稿は出発点であり、最終回答ではありません。人が確認してください

---

失敗パターン

ドキュメント作成を「後で」やるタスクにする。 いつも後回しにされます。後でとは、決してやらないということです。ドキュメント作成を作業の一部にしましょう。

すべてを1つの巨大なドキュメントにまとめる。 8,000語のWikiページは、誰も読みません。カテゴリやトピックごとに分けましょう。

誰も信頼しない古いドキュメント。 「おそらく古い」という考えが、ドキュメントを無用にします。最新の状態に保つか、アーカイブしましょう。

必要だと誰もが同意しているのに、誰も書かないドキュメント。 オンボーディング用ドキュメントが役立つとチームが同意しても、何か月も過ぎ、誰も書きません。担当者を明確にしましょう。

墓場のようなWiki。 ページはたくさんあっても、誰も信頼していません。監査してアーカイブし、より簡潔な構成で再スタートしましょう。

コードと切り離されたドキュメント。 API ドキュメントはWikiにあり、コードはリポジトリにあります。両者にずれが生じます。同じ場所にまとめましょう。

例のないドキュメント。 例のないリファレンスは使いにくいものです。例を使って具体的にしましょう。

実行できない例。 かつては動作していたコード例も、時間とともに実態とずれていきます。可能であれば、CIで例をテストしましょう。

リファレンスで済む内容を長文で説明する。 30行の表で説明できる内容に、2,000語のドキュメントを作成してしまうことがあります。適切な形式を選びましょう。

複数の信頼できる情報源。 同じ情報が3か所にあり、それぞれ少しずつ異なっています。正規の情報源を1つ決め、他の場所からはそこに誘導しましょう。

誰も使わないドキュメントツール。 機能を理由に導入しても、チームが実際には使っていないことがあります。チームが使うツールを選びましょう。

ドキュメントより長いスタイルガイド。 プロセスが成果物より重視されています。ガイドは短くしましょう。

ドキュメントを非推奨として示す方法がない。 古いドキュメントが現行のものと並んでいても、見分けがつきません。「非推奨」や「アーカイブ済み」のステータスを追加しましょう。

分析データがない。 何が使われているのか、何が不足しているのかがわかりません。基本的なページビューだけでも、優先順位を決める参考になります。

仕様書のようなドキュメント。 情報が詰め込まれ、形式張っていて、ざっと読みにくいものです。読者のために書きましょう。

---

出力形式

ドキュメント戦略文書には、以下を含めます。

• 監査： 存在するもの、その場所、状態
• 階層化と分類： 既存のドキュメントに適用したフレームワーク
• ギャップ一覧： 作成すべきだが、まだ存在しないもの
• ツールに関する決定： 各種ドキュメントの保管場所
• オーナーシップマップ： 各項目の担当者
• メンテナンスの頻度： 何をいつ見直すか
• スタイルガイド（簡易版）： 一貫性を保つための基準
• ロードマップ： ギャップを埋め、不要なものを整理するための優先順位付き作業

---

参考ファイル

• references/doc-types-guide.md：4種類のドキュメント（リファレンス、ハウツー、解説、チュートリアル）について、各種類の例とテンプレートを含む詳細なガイドです。