2026年4月3日

「社内だけ Git、配布は PDF」開発チーム向けドキュメントフロー

PM・エンジニア向け。Git（Markdown）で仕様管理→タグ付きコミットからPDF生成という社内ドキュメントフロー。レビュー・承認・配布・版管理・機密対応まで実務チェックリスト付き。

想定する読者とシーン

次のようなチームを想定しています。

プロダクトマネージャー（PM）：スコープや優先度が変わるたびに「どの版の仕様が公式か」を関係者に説明したい。
エンジニアリングマネージャー／テックリード：設計判断や運用手順を レビュー可能な形で残し、後から追いたい。
開発者（IC）：API 仕様・エラー仕様・リリース手順などを Issue／PR と突き合わせやすい形で書きたい。

共通の悩みは、「社内では Git で十分だが、顧客・営業・法務・他部署には PDF の方が通りやすい」というギャップです。この記事では、そのギャップを 運用で埋めるための型を整理します。

なぜ「Git」と「PDF」を分けるのか（担当別の見方）

観点	Git（Markdown）	PDF（配布物）
PM	変更履歴と差分で「いつ何が変わったか」を説明しやすい	締結・稟議・納品で版が固定していることが重要
エンジニア	PR レビュー・ブランチ戦略と相性がよい	印刷・オフライン閲覧・レイアウト固定のニーズに応えやすい
社外ステークホルダー	アカウントや Git の知識が前提になりがち	添付ファイルとしてそのまま回せる

1 つのファイルに「執筆用」と「配布用の装飾」を詰め込むと、Markdown が肥大化し、レビュアーが本質の差分を読みにくくなることが多いです。執筆と履歴は Git、読み手に渡す「顔」は PDF と役割を分けるのが現実的です。

ドキュメントの種類と置き場所（ざっくり分類）

運用を設計するときは、次のように 種類ごとに置き場所のルールを決めると迷子が減ります。

プロダクト仕様・API 仕様 … docs/spec/ や docs/api/。リリース単位で読むことが多い。
アーキテクチャ決定（ADR） … docs/adr/。決定の背景を短く残す。
運用・リリース手順 … docs/runbooks/。インシデント対応やリリースチェックリスト。
顧客向けの約束事 … 文言が契約に直結する場合は、タグ付きコミットから PDF を切るなど、版の扱いを厳めに。

「全部 docs/README に書く」でも動きますが、チームが大きくなるほど フォルダで意味を分けるほうが、PM・エンジニアどちらからも発見しやすくなります。

ライフサイクル：草案 → レビュー → 承認 → タグ → PDF

ざっくり次の流れに揃えると、**「どれが公式版か」**が説明しやすくなります。

草案：フィーチャーブランチまたは docs 専用ブランチで Markdown を更新する。
レビュー：PR で PM・関係エンジニアが読む。仕様変更と Issue／チケットを紐づける。
承認：チームのルールに応じて「LGTM」「承認者 1 名」などを満たしてマージ。
タグ：リリースや「この版を顧客に見せる」タイミングで Git タグ（例：docs-v2.1）を打つ。
PDF：タグが指すコミットの Markdown から PDF を生成し、リリースノートや共有ドライブに添付する。

毎コミットで PDF を作り直す必要はありません。「この版が公式」というイベントで PDF を切ると、運用と説明の両方が楽です。

PM が押さえるとよいこと

マイルストーンとの対応：「このスプリントで凍結する仕様はどこまでか」を、ドキュメントの章や Issue と対応づける。
スコープ変更の可視化：仕様変更が入ったら、PR の説明にビジネス上の理由を一行でも書く（後から監査や振り返りがしやすい）。
社外向けの「約束」：契約書や SOW と突き合わせる版は、PDF のファイル名と Git タグをセットで記録する（例：リリースノートに「公式 PDF は spec-v2.1.pdf（タグ docs-v2.1）」）。

エンジニアが押さえるとよいこと

PR を仕様変更の単位にする：コードと同じく、レビュー可能な差分の大きさで PR を分ける。
CODEOWNERS：docs/api/ にはバックエンド、docs/runbooks/ には SRE、といった レビュー先のデフォルトを決める。
Issue とのリンク：「なぜこの仕様になったか」を、PR や ADR に残す（ツール名は問わない）。

CI で PDF を自動生成するチームもありますが、**まずは「タグを打った人がブラウザで PDF を切る」**でも十分運用できます。自動化はドキュメントが安定してからでよい、という割り切りも有効です。

配布用 PDF の命名と保管

ファイル名：{ドキュメント名}-{版}.pdf のように、版が分かる形にする（例：api-spec-v2.1.pdf）。
保管場所：リリースノート、社内 Wiki の「公式リンク」欄、顧客ポータルなど、「ここを見ればよい」場所を一つに寄せる。
Markdown との対応：README かリリースノートに「ソースはタグ docs-v2.1」と書いておくと、PDF と Git が食い違ったときの手がかりになります。

ブラウザで PDF 化する意味（機密・コンプライアンス）

顧客名・未公開仕様・個人情報が含まれるドキュメントでは、クラウドの変換サービスに本文を送りたくないという要件が出ます。ブラウザ内で Markdown を読み込み、プレビューとレイアウトを確認してから PDF 保存する方式なら、ファイルがサーバーにアップロードされない前提で設計できます（本サイトのツールもその考え方です）。

社内規程で「利用できるツール」が決まっている場合は、セキュリティレビューに通しやすいという利点もあります。

うまくいかないとき

状況	考え方
PDF ばかり増えて最新がわからない	Git のタグ／リリースノートに「公式 PDF はこれ」と必ず書く
Markdown と PDF の内容が食い違う	PDF はタグ付きコミットからのみ生成するルールにする
PM とエンジニアで認識がずれる	PR で仕様の合意を取り、顧客向け PDF はマージ後だけに限定する
Git を使えないステークホルダーがいる	草案は共有ドキュメントでもよいが、確定版は PDF＋タグで固定する

リリース前チェックリスト（例）

次を満たしてから PDF を社外に出す、というチェックをチームでテンプレ化すると強いです。

対象の Markdown が main（またはリリースブランチ）にマージされている
Git タグが打たれ、リリースノートにタグ名が書かれている
PDF の ファイル名に版が含まれている
顧客向けに必要なら 法務・営業の確認が済んでいる
機密が含まれる場合、ブラウザ完結など社内ルールに沿った生成方法になっている

まとめ

**Git（Markdown）**は差分・レビュー・履歴のため、PDFは固定版の配布のため、と役割を分ける。
PMはマイルストーン・スコープ・社外向けの「公式版」の説明責任を、エンジニアは PR・CODEOWNERS・Issue 連携で支える。
版のブレを防ぐには タグ＋PDF 命名＋リリースノートをセットにする。
機密配慮があれば ブラウザ完結の PDF 化を選択肢に入れる。

操作の細部は Markdown を HTML・PDF に変換する使い方・手順ガイド、改ページの調整は Markdown PDF の改ページを自分で決める方法も参照してください。

社内ドキュメントを PDF で配布する（ツールを開く）