技術ドキュメントの構成設計｜読まれるMarkdownの組み立て方

結論：1ファイルに全部書かず、読者と更新頻度で分割する

Markdownの記法が書けるようになっても、1つのREADMEに全部詰め込むと誰も読まなくなります。技術ドキュメントの構成設計では、「誰が・いつ・何を知りたいか」でファイルを分け、READMEは入口、詳細は docs/、意思決定の履歴は adr/ のように役割を固定します。結論から言うと、更新頻度と読者が同じものだけを同じファイルに置くのが保守しやすいドキュメントの原則です。

ドキュメントの種類と役割

中小チームでも次の4種類に分けると迷いが減ります。

• README：初見の利用者・開発者が5分で動かすための入口
• How-to（手順書）：デプロイ、障害対応、開発環境構築など手順固定の作業
• Reference（参照）：環境変数一覧、APIエンドポイント、CLIオプション
• Explanation（解説）：アーキテクチャ、設計思想、トレードオフ

Diátaxis（ディアタクシス）というフレームワークでこの4分類が整理されています。検索ニーズは「やり方」「一覧」「なぜそうなったか」で異なるため、混在させないと検索性が上がります。

ディレクトリ構成の例

project/
  README.md
  CONTRIBUTING.md
  docs/
    index.md          # ドキュメントの目次
    getting-started.md
    configuration.md
    api/
      overview.md
      endpoints.md
  adr/
    0001-use-sqlite.md
    0002-auth-strategy.md

docs/index.md から各ページへリンクし、READMEには「詳細は docs を参照」と一行書く形がよく使われます。静的サイトジェネレーター（MkDocs、Docusaurus、VitePress）を使う場合も、この構造をそのまま活かせます。

失敗例：docsがコピペの墓場

ConfluenceやWordから一度だけ持ってきた長文が、更新されずに残るパターンです。READMEだけ最新で、docs内は古いコマンドのまま、というドキュメント負債になります。対策は、手順書を短く保ち、コマンドはCIやスクリプトと一緒にレビュー対象にすることです。

ADR（Architecture Decision Record）

「なぜSQLiteにしたか」「なぜRESTにしたか」はREADMEに書くと長くなりすぎます。ADRは1決定1ファイルで、次のテンプレートが一般的です。

# ADR 0001: データベースにSQLiteを採用

## 状況
小規模チーム、単一ノードデプロイ

## 決定
初期リリースはSQLiteを使用する

## 結果
運用コストは低いが、水平スケール時に再検討が必要

## ステータス
承認（2024-03-01）

番号を付けて時系列に並べると、後から入ったメンバーが設計の経緯を追えます。却下した案も簡潔に残すと、同じ議論の繰り返しを防げます。

読者別の書き分け

同じ機能でも、利用者向けと開発者向けで必要な情報は違います。

• 利用者：インストール、設定の最小例、トラブル時のFAQ
• 開発者：ディレクトリ構成、テストの走らせ方、コーディング規約
• 運用者：デプロイ、ログの見方、バックアップ、SLA

見出しの先頭に「開発者向け」と明示するか、ファイル名に dev- ops- を付けると、誤読が減ります。

見出しと命名の規約

チームで次を決めておくと、複数人執筆でも統一感が出ます。

1. 見出しレベルは # をREADMEに1つ、以降 ## から
2. ファイル名は英小文字＋ハイフン（getting-started.md）
3. 日付はISO形式（2024-05-30）で書く
4. 用語集（glossary.md）に略語を集約する

バージョンと製品の対応

「v2から設定が変わった」は、本文中に Since v2.0 のように書くか、バージョン別フォルダ docs/v2/ を切ります。古いバージョン用ドキュメントを残す場合は、先頭に「このページは旧バージョン向け」と警告を入れ、現行版へのリンクを置きます。

用語集（glossary）の置き方

略語が多いドメイン（API、インフラ、機械学習）では、docs/glossary.md に用語と定義を集約します。本文では初出時にリンクし、2回目以降は略語のみで済ませます。用語の揺れ（「ユーザー」「利用者」）を防ぐ効果もあり、複数人執筆のプロジェクトでは早めに用意するとよいでしょう。

レビューとメンテナンスの仕組み

コードのPRに「ドキュメント更新」をチェックリストに含める文化が、陳腐化を防ぐ最も効く手段です。機能追加PRで docs/ またはREADMEの差分がゼロなら、レビュアーが確認質問をするだけでも効果があります。四半期ごとに「リンク切れチェック」「主要コマンドの手動実行」をカレンダーに入れるチームもあります。

CHANGELOGとREADMEの役割分担

バージョンごとの変更点は CHANGELOG.md に時系列で書き、READMEには「最新版の使い方」だけを残します。利用者はREADME、既存利用者のアップグレードはCHANGELOGを読む、という導線が明確になります。破壊的変更（APIの削除など）はCHANGELOGの先頭に目立つよう書き、READMEの「移行ガイド」から該当セクションへリンクすると親切です。semverに従うチームでは、CHANGELOGの書式もテンプレート化しておくと漏れが減ります。

障害対応Runbookの例

運用向けHow-toでは、症状・確認コマンド・暫定対応・恒久対応・連絡先を固定見出しにします。長文化したRunbookは1障害1ファイルに分割し、indexからリンクします。深夜のオンコールで検索しやすいよう、見出しには障害名（「DB接続タイムアウト」）をそのまま使うのが現場では好まれます。

まとめ

構成設計は、Markdown記法より情報の分割と更新ルールが本質です。READMEは入口、手順・参照・解説・ADRで役割を分け、読者とバージョンを明示し、PRレビューでドキュメントを同時に更新する。次回は、執筆を支えるエディタ・プレビュー・Lintツールを扱います。