公開意思決定履歴サイトの作り方

公開意思決定履歴とは（そして何ではないか）

公開意思決定履歴は、重要なプロダクトの意思決定を厳選して記録し、ウェブサイトで公開するものです。読む人が「何を選んだか」「いつ選んだか」「当時なぜその選択が妥当だったか」を理解できるようにします。

ドキュメントやチェンジログの隣にある「根拠レイヤー」と考えてください。マーケティング文ではなく、会議の議事録でもありません。推測を減らし、整合を早め、同じ議論が数か月ごとに再燃するのを防ぐ実用的な参考資料です。

何であるか

良い公開意思決定履歴は：

• ユーザーや貢献者に影響する決定を記録する（機能、廃止、価格モデルの変更、セキュリティの姿勢、API原則、UXの慣習など）
• 状況と制約を説明する（顧客のニーズ、法規制、技術的制約、タイミング）
• 検討した選択肢と受け入れたトレードオフを示す
• 「なぜこうしたのか？」と問われたときに参照できる安定したURLを指し示せるようにする

何ではないか

期待値を明確にするために、公開しないものをはっきりさせておきます：

• すべての内部会話ではない：成果のログであり、Slackや通話、議論の再生ではありません。
• 将来の作業の約束ではない：行われた決定を記録するもので、ロードマップではありません。
• 機密詳細の置き場ではない：顧客の私人情報、脆弱性、内部指標をさらすことなく理由を説明できます。

なぜ公開するか（実務的な目的）

多くのチームが公開意思決定履歴を公開する目的は：

• 一貫した論拠を示して信頼を築くため
• 顧客、パートナー、新しいチームメンバーのオンボーディングを速めるため
• 正式なエントリにリンクすることで繰り返される議論を減らすため（「これは既に決まっている」）

誰を対象にするか

主な読者には通常以下が含まれます：

• 製品の適合性や長期方針を評価する顧客
• 製品と統合するパートナー
• 基準に合意するための貢献者（オープンソースやコミュニティ）
• 一次情報を求める報道関係者やアナリスト

主要な読者を特定できれば、各エントリは短く、明確で、より有用になります。

範囲：どの決定を公開するか

公開意思決定履歴は、読者が何を見つけられるかを予測できるときに最も効果的です。すべてを公開すると雑多になり、成果だけを公開するとマーケティングのように見えます。チームにとって一貫性があり、役立ち、持続可能な範囲を定義してください。

まずは決定の種類に名前を付ける

キャプチャしたいカテゴリを一覧にし、各カテゴリの簡単なルールを書きます。一般的なタイプは：

• プロダクト機能：なぜその機能を作った（または削除した）のか、どの問題を解決するのか
• 価格とパッケージ：プランの変更、制限、トライアル、割引ポリシー
• セキュリティとプライバシー：意味のある改善、トレードオフ、顧客向けの影響
• UXとデザイン：主要なインタラクション変更、アクセシビリティの決定、ナビゲーションの変更

良いテストは、顧客が「なぜこうしたのか？」と尋ねる可能性があるかどうかです。たいてい該当します。

維持可能な期間を選ぶ

決定を公開する開始点を決めます：

• 最初の日から（新しいプロダクトでは理想的）
• 特定のマイルストーンから（例：「v2.0以降」）
• 主要リリースのみ（現実的な出発点）

過去の履歴を遡って埋める場合は、明確なカットオフを選んでイントロの注記で示してください。不完全に見えるよりは、明示する方が良いです。

適切な詳細レベルを選ぶ

すべての決定に長い説明が必要なわけではありません。二段階に分けて運用するとよいでしょう：

• 短いエントリ：3〜6文の要約と関連ドキュメントやリリースへのリンク
• 詳細な書き下し：影響の大きい決定（価格、破壊的変更、信頼/安全）に使用

長さより一貫性が重要です。読者は頼りになるフォーマットを求めます。

非公開にするものを定義する

ケースバイケースの議論を避けるために、除外事項を事前に書き出してください：

• セキュリティ上敏感な詳細（攻撃経路、内部の管理）
• 個人データ（顧客、従業員、インタビュー記録）
• 契約や交渉の具体的内容
• 悪用されればユーザーや競争上の不利になる内部指標

詳細を省略しなければならない場合は、簡単な「共有できること」ノートを付けて、エントリが正直で完結していると感じられるようにしてください。

決定エントリのテンプレートと必須フィールド

公開意思決定履歴は、各エントリが同じ核心的な質問に答える場合にのみ機能します。読者は、何を解決しようとしていたのか、どの選択肢を検討したのか、選択後に何が変わったのかを推測してほしくありません。

コアテンプレート（Context → Options → Decision → Rationale → Impact）

各決定ページには一貫した構造を使ってください。反復可能な流れが作成者を規律し、スキャンを容易にします：

• Context（文脈）：決定を引き起こしたトリガーは何か？制約（時間、予算、ポリシー）、ユーザーニーズ、関連背景を含める。
• Options（選択肢）：評価した実際の代替案（通常は2～4つ）。トレードオフを簡潔に記す。
• Decision（決定）：選んだオプションを明確に記載。
• Rationale（根拠）：なぜそのオプションを選んだか。主要因と仮定を含める。
• Impact（影響）：決定後に何が変わったか—ユーザーに見える挙動、内部プロセス、廃止、あるいは新たなリスク。

必須メタデータ（エントリをソートし信頼できるものにするため）

各エントリの冒頭に小さな“ヘッダー”ブロックとしてフィールドを追加してください：

• Date（決定日）（必要なら「発効日」も）
• Status（ステータス）：proposed / accepted / reversed（または superseded）
• Owners（責任者）：アカウンタブルな人物/チーム（必ずしも執筆者とは限らない）
• Tags（タグ）：プロダクト領域、顧客セグメント、プラットフォーム等
• Audience（想定読者、任意）：顧客、パートナー、社内ユーザーなど

このメタデータは後でフィルタやタイムラインを作る際に重要で、決定の確定度合いも示します。

検証可能なものへのリンクを張る

読者が成果やアーティファクトに辿れると決定はより信頼されます：

• 関連するチェンジログのエントリ（例：/changelog/2025-04-18-search-update）
• 補足ドキュメント（例：/docs/search/indexing）
• リリースノートやバージョンページ（例：/releases/1.12）

反転や「上書き」になった決定の計画

反転は普通のことです—明確に公開してください。決定が置き換えられた場合：

• Status を reversed または superseded に変更
• Superseded by を追加して新しいエントリを指す（例：/decisions/014-new-rate-limits）
• なぜ変更されたか（新データ、予期せぬコスト、方針変更）を短く記載

これにより履歴は正直さを保ちつつ、単に過去を塗り替えることは避けられます。

情報アーキテクチャとナビゲーション

公開意思決定履歴は、読者が「何が起きたか？」と「このことを説明する決定はどこにあるか？」の二つの質問に素早く答えられるときにのみ機能します。情報アーキテクチャは、初めて製品を見る人にも直感的に閲覧できるように設計してください。

人々が探す方法に合った主要ナビゲーションを選ぶ

多くのチームは3〜4のトップレベル項目が最適です：

• Timeline（タイムライン） — 物語を時系列で追いたい人向け
• Topics/Tags（トピック／タグ） — 「価格」「API」「アクセシビリティ」「セキュリティ」などのテーマへジャンプする方法
• Key Decisions（重要決定） — よく参照される決定のキュレーション
• About（このサイトについて） — サイトの範囲、含まれるもの・除外されるもの、エントリの解釈方法

トップナビは安定させておきましょう。後で新しいページ（例：「Methodology」）を追加する場合は、メインメニューを拡張するのではなく About の下に入れるとよいです。

URLパターンを決める（後で変えない）

明確なURLは共有・引用・検索を容易にします。よく使われるシンプルな例：

• /decisions/2025-03-feature-flags

日付を使うとソートしやすく、人間が読める短いスラッグをつけてください。1か月に多くの決定がある見込みなら日付（例：/decisions/2025-03-18-feature-flags）を含めます。公開後にURLを変更するのは避け、どうしても変更する場合はリダイレクトを追加してください。

「まずはこちら」ページを追加する

短いガイドを置くことで混乱を減らし、ドラフトや部分的な記録を誤って解釈されるのを防げます。/start-here のような目立つページ（ヘッダーや About からリンク）を作り、以下を説明してください：

• サイト上で「決定」と見なされるもの
• タグ、検索、フィルターの使い方
• ステータスラベルの意味（例：Proposed, Accepted, Reversed）
• 更新や改訂の読み方

まずスキャンしやすく、次に深掘りできる設計にする

ほとんどの訪問者は斜め読みします。各決定ページを次のように構成してください：

• 一段落の要約（何が変わり、なぜか）
• トップに近い場所に主要メタデータ（日付、ステータス、オーナー）
• 下に詳細な根拠を置き、折りたたみ可能にするセクションを用意

一覧（タイムライン、トピック）ではカード形式でタイトル、日付、1〜2行の要約を表示すると良いです。読者は多くのエントリを開かずにブラウズでき、詳細はクリックで開けます。

データモデル：決定の保存方法

公開意思決定履歴は基盤構造の良し悪しで有用性が決まります。読者が信頼できるリンクを得られず、フィルタできず、関連関係が不明瞭だと、サイトは単なる投稿の寄せ集めになってしまいます。

チームに合った最もシンプルな保存方法を選ぶ

一般に三つの選択肢があります：

• リポジトリ内のMarkdownファイル：バージョン管理、レビュー、低コストに優れます。静的サイトジェネレータやGitベースのワークフローと相性が良いです。
• CMSエントリ：非技術系の編集者が多い場合や、ドラフト／承認機能が必要な場合に向きます。ただしURLやエクスポート制御は注意が必要です。
• データベースレコード（カスタムアプリ）：複雑な関係性や分析が必要な場合に最適ですが、構築・維持の手間が最大になります。

特別な関係性が既に必要でない限り、まずはMarkdownかCMSで始めるのが良いでしょう。

壊れないリンクのために安定した一意IDを使う

各決定を恒久的な記録として扱ってください。タイトルが変わっても変わらない決定IDを割り当てます。

例：

• DEC-00127
• PDH-2025-04-15-analytics-export

URLの一部としてIDを使えば、ページ名を変更してもサポートチケットやドキュメントからのリンクが切れません。

フィルタやナビゲーションを支えるフィールドをモデル化する

すべてのフィールドを公開する必要はありませんが、後でフィルターを作れるように最初に定義してください。一般的なフィールド：

• Product area（例：Billing、Reporting）
• Customer segment（例：SMB、Enterprise）
• Status（Proposed、Decided、Revisited）
• Release（バージョン、日付、/changelog へのリンク）
• Decision date と effective date
• Tags（privacy、pricing、performance など）

添付ファイルの保存方法を計画する

図、スクリーンショット、PDFの保管場所を決めてください：

• 軽量な画像は決定エントリ近くに置く（例：/assets/decisions/DEC-00127/ フォルダ）
• PDFや大きなファイルは安定したファイルパスに置き、決定IDで命名する

いずれにしても、添付URLは予測可能にしておくとサイトの進化に伴って有効性が保てます。

ツール選定：静的サイト、CMS、またはカスタムアプリ

ツールは二つの点に合わせるべきです：どれだけ頻繁に決定を公開するか、そしてどれだけリーダー体験（検索、フィルター、関係性表示）が必要か。多くのチームはまずシンプルに始め、アーカイブが成長したらより複雑なものに移行します。

オプション1：静的サイト（迅速で低メンテナンス）

静的サイトジェネレータ（ドキュメントスタイルのサイト）はMarkdownを高速なウェブサイトに変換します。公開意思決定履歴を立ち上げる最も簡単な方法であることが多いです。

向いているのは：

• 決定を時々または決まったペースで公開する場合
• フィルタニーズが基本的（プロダクト領域、日付、ステータス）な場合
• 運用負担を低く抑えたい場合（サーバー不要、可動部品が少ない）

静的サイトは「決定をコードとして扱う」運用とも相性が良く、各決定をリポジトリ内のMarkdownファイルとしてプルリクでレビューできます。高品質な全文検索が必要ならホスト型検索サービスを組み合わせると自前で作る必要がありません。

オプション2：GitベースのMarkdown vs ヘッドレスCMS

GitベースのMarkdownはプルリクに慣れた貢献者に最適で、レビューと履歴が内蔵されています。

一方、ヘッドレスCMSは非技術系の執筆者が多い場合や、フォームで構造化フィールドを強制したい場合に向きます。公開は静的サイトに対して行うことが多いですが、編集はCMS上で行います。

オプション3：カスタムアプリ（高度なフィルタと関係性）

複雑な多選択ファセットや多対多のリンク（決定 ↔ リリース ↔ ドキュメント）が必要ならカスタムアプリが適します。ただし継続的なエンジニアリングとセキュリティ対策が必要です。

カスタムアプリの利点を短い開発で得たい場合は、データモデル（決定エントリ、タグ、ステータス、置き換えリンク）、ページ（Timeline、Topics、Key Decisions）、管理ワークフローを定義して素早く反復するアプローチが実用的です。

（原文の例として Koder.ai による支援が挙げられていましたが、ここでは自社のニーズと予算に合わせて代替を検討してください。）

検索とプレビュー環境

検索には次を選べます：

• 組み込みサイト検索（セットアップが早いが機能は限定的）
• ホスト型検索（最良の関連性とフィルタ）
• サーバーサイド検索（最も柔軟だが運用コストが高い）

いずれを選ぶにせよ、プレビュービルドを用意してレビュワーが公開前に実際の表示を確認できるようにしてください。ドラフトごとに「プレビュー」リンクがあるだけで手戻りが減り、ガバナンスも軽量に保てます。

検索、フィルター、読者体験

公開意思決定履歴は、人々が目的の決定を素早く見つけて理解できるときに初めて有用です。検索とナビゲーションを見た目の飾りではなくプロダクト機能として扱ってください。

意図を理解する全文検索

まずはタイトル、要約、主要フィールド（Decision、Status、Rationale）を横断する全文検索を実装してください。人々は社内用語を知らないことが多いので、検索は部分一致や同義語を許容すべきです。

検索にフィルタを組み合わせて、結果を速く絞り込めるようにします：

• タグ（例：「pricing」「API」「privacy」）
• ステータス（proposed、accepted、reversed、deprecated）
• 日付範囲（四半期、年、カスタム）
• エリア／オーナー（チーム、プロダクト面、地域）

デスクトップではフィルタを常時表示し、モバイルでは開閉しやすくしてください。有効なフィルタは「チップ」として表示し、ワンクリックで「すべてクリア」できるようにします。

文脈のためのクロスリンク（ただし乱立させない）

多くの読者はチェンジログ、サポートチケット、SNSスレッドから来ます。次のリンクで文脈を補助してください：

• 関連決定（依存、代替、supersedes / superseded by）
• 成果（指標、学び、フォローアップ）
• 補助ドキュメント（リリースノート、ポリシーページ、FAQ）

リンクは目的を持たせてください：1〜2件の「関連」が長いリストより有益です。エントリに一意のIDがある場合はIDで検索できるようにし、タイトルの近くに表示して参照しやすくしてください。

「最後に見たときから何が変わったか」

更新や新規決定を強調する Recent ビューを追加すると便利です。実装例：

• /decisions/recent を更新日時順で表示
• 更新のための RSS/Atom フィード（報道やパートナー向けに有用）

ユーザーアカウントをサポートするなら最後の訪問時刻に基づく「前回以降の更新」も可能ですが、シンプルな recent リストで十分なことが多いです。

アクセシビリティと読みやすさ

見出し構造（H2/H3）、十分な色コントラスト、読みやすいフォントとサイズを使ってください。検索、フィルター、ページネーションのキーボード操作を保証し、フォーカスの可視化を提供してください。要約は短く、スキャンしやすいセクションにし、密な長文は避け、読者が1分以内に決定の要点を把握できるようにします。

公開ワークフローとガバナンス

公開意思決定履歴は、エントリが完全で一貫しており配慮を持って書かれていると読者が信頼できる場合にのみ有用です。重い官僚主義は不要ですが、ドラフトから公開までの反復可能なパスと明確な所有は必要です。

役割を定義する（兼任でも可）

各エントリについて誰が何をするかを決めてください：

• Author（作成者）：決定を書き、文脈を説明し、補助資料にリンクし、最終文言を提案する人。
• Reviewer（レビュアー）：明確さと網羅性をチェックし、仮定に異議を唱え、リンクや参照が正確か確認する人。
• Approver（承認者）：決定が実際のものであること、現時点で妥当であること、内部承認（プロダクトリーダーシップ、セキュリティ、法務など）に合致することを検証する人。
• Publisher（公開者）：公開基準を満たしているか確認し、タグ／ステータスを適用してサイトに公開する人。

各エントリに「Author / Reviewer / Approver」を表示してプロセスの透明性を保つと良いです。

軽量な公開前チェックリストを使う

短いチェックリストで品質問題の多くを防げます：

• 明瞭性：非専門家が一度読んで要約できるか？
• リンク：関連ドキュメント、チケット、調査、リリースへのリンクがあるか？
• 機密情報：顧客データ、セキュリティ詳細、契約条件、社内計画が露出していないか？
• トーン：中立かつ事実ベースか（非難や皮肉がなく、トレードオフを公正に説明しているか）

テンプレートを作る場合は、このチェックリストをドラフト内に組み込むとレビュープロセスが効率化します。

編集ルール：履歴を書き換えずに誤りを訂正する

決定は歴史的記録です。修正が必要な場合は付加的な変更を優先してください：

• 誤字／フォーマット修正は無音で行う。
• 事実訂正は短い**「更新」ノート**を日付付きで追加する。
• 決定内容が変わる場合は、新しい決定エントリを公開し、古いものにリンクして「Supersedes …」とする（古い結論を書き換えない）。

執筆基準を公開する

/docs/decision-writing のような短いガイドページを追加して、以下を説明してください：

• 公開に値する決定の条件
• 期待される構成と語彙
• 不確実性やトレードオフの扱い方
• 先述の編集ポリシー

これにより寄稿者が増えても声の一貫性が保て、レビュアーの負担も減ります。

プライバシー、セキュリティ、法務上の配慮

決定理由を公開することは信頼を築きますが、誤って共有してはならない情報が公開されるリスクも高めます。公開意思決定履歴を生の内部ノートのエクスポートと見なさず、精査された成果物として扱ってください。

削除：公開してはならないものを決める

まずは明確な削除ルールセットを作り、一貫して適用してください。一般的に「常に削除すべき」項目：個人データ（名前、メール、通話記録）、顧客固有の詳細（アカウント情報、契約条件、更新日）、悪用を招く可能性のあるもの（セキュリティの所見、内部管理用URL、詳細なシステム図、正確なレートリミット）

機密性の高い入力に基づく決定でも、理由の大まかな形を示すことは可能です：

• 証拠を要約する（例：「サポートがEUのカード決済で繰り返し失敗を報告」）
• 識別子を広いカテゴリに置き換える（例：「あるエンタープライズ顧客」）
• 詳細は留保する旨を明示する（例：「セキュリティチームの推奨—詳細は非公開」）

法務／コンプライアンスレビュー：軽量なゲートを設ける

すべての決定に法務レビューが必要なわけではありませんが、必要なトピック（価格変更、規制業界の対応、アクセシビリティ主張、プライバシーポリシーの影響、パートナー契約）は定義しておきます。

手順はシンプルに：チェックリストと指定レビュアー、ターンアラウンドの期待値を決めておくこと。目的はリスクを回避しつつ公開を停滞させないことです。

意図的に省略しているものを明示する

About ページやフッターに短いポリシーノートを置き、「保護のために公開しないもの」とその理由（ユーザー保護、契約順守、セキュリティ露出の低減）を説明してください。これにより読者の推測を減らせます。

修正と懸念の報告経路を作る

読者が問題を報告したり修正を依頼したりプライバシー懸念を伝えられる明確な方法を用意してください。/contact のような専用チャネルへのリンクを置き、応答時間を約束します。テイクダウン要求の処理方法や改訂の表記方法（例：「2026-01-10に顧客識別子を削除のため更新」）も文書化しておきましょう。

決定をリリース、ドキュメント、成果に結びつける

決定ページは、何が出荷され何が変わりその後どうなったかが検証できるときに最も有用です。すべての決定をハブとして、リリースやドキュメント、実際の成果へと導いてください。

決定とリリース／チェンジログをリンクする

各決定エントリに小さな「Shipped in」ブロックを追加して該当するリリースノートへのリンク（例：/changelog）とリリース日、バージョンを示してください。これにより読者は意図と現実の接続を確認できます。

決定が複数のリリースにまたがる場合は順に列挙し、各フェーズで何が変わったかを明確にしてください。

「関連ドキュメント」リンクを維持する

決定は「なぜ」を説明し、ドキュメントは「どうやって」を説明します。決定ページにその決定で作成または更新された /docs の特定ページへの「Related docs」セクションを含めてください。

リンク切れを防ぐために：

• 公開ワークフローに「ドキュメントリンクチェック」を組み込む（四半期ごとのレビューでも効果あり）
• 安定したドキュメントURLを好む（日付ベースのスラッグは避ける）

意図だけでなく成果も示す

リリース後に更新する「Outcomes（成果）」セクションを追加してください。事実ベースで：

• 追跡する指標（例：サポートチケット数、アクティベーション率、完了時間）
• 受けたフィードバック（生の引用ではなく要約されたテーマ）
• フォローアップタスク（公開されているIssueへのリンクか、短い一覧とステータス）

「結果：混在」でも、学びと次に何を変えたかを説明すれば信頼につながります。

「最も参照された決定」の索引を作る

オンボーディングのため、内部リンク数、ページビュー、docsやチェンジログからの引用数でランク付けした「最も参照された決定」一覧（またはサイドバー）を追加してください。これにより新しい読者は製品形成に大きく影響した決定に素早く辿り着けます。

効果測定と改善

公開意思決定履歴は、人々が実際に答えを見つけ信頼することが重要です。サイトをプロダクトとして扱い、利用状況を測り、失敗箇所を学び、小さなサイクルで改善してください。

実際に使われているものを追跡する

軽量な行動分析から始めてください。虚飾的な指標ではなく利用に関するものを重視します：

• 上位ページ：よく読まれる決定（クロスリンクや要約の改善候補）
• 検索で結果がないクエリ：欠けているタグ、曖昧なタイトル、未公開の決定を発見する最速手段
• ページ滞在時間と離脱：長い滞在は高関心か混乱を示す。フィードバックプロンプトで補完する

/ search ページがあるなら匿名化したクエリログを保持して何を探されたかを確認してください。

文脈に沿ったフィードバックを集める

各決定ページ上で直接回答できるようにしてください。コンテキストが新しいうちにフィードバックを得るためです。シンプルな「役に立ちましたか？」のプロンプトと短いテキスト欄で十分なことが多いです。あるいは「この決定について質問する？」リンクで決定URLを事前入力したフォームに誘導する方法もあります。

フィードバックは共有の受信箱やトラッカーに流すようにして、個人のメールに埋もれないようにしてください。

成功の指標を定義する

観察可能な成果をいくつか選んでください：

• 同じトピックに関する繰り返し質問の減少（顧客／パートナー／サポートからの）
• 関係者の合意までの時間短縮（過去の争点が再度議題になる回数の減少）
• 質の高い議論の増加：結論だけでなく根拠やトレードオフを参照したフィードバック

実行可能な周期を設定する

月次レビューを予定して：

• 重複の整理や統合
• タグとクロスリンクの補完
• 不明瞭な要約の書き直し
• 検索に効くタイトルへの改善

変更は可視化しておき（例：「Last updated」フィールド）、サイトが維持されていることを読者に示してください。