ドキュメント体系のつくり方

規約の正本

執筆ルールの正本は二段構えである。

判断と理由は、ガイドラインのドキュメントを正本とする。
文体や表記など機械的に検証できる規約は、lint 設定を正本とする。

機械的な規約の具体値は、ドキュメントへ書き写さない。二重管理を避け、出どころを lint 設定だけに保つためである。

置き場所の決め方

置き場所は Diátaxis の4分類で決める。1ページには1つの分類だけを書き、種類を混ぜない。

チュートリアル: 初学者が手を動かして学ぶための文章を置く。
ハウツー: 特定の課題を解決する手順を置く。
リファレンス: 仕様や事実を引くための記述を置く。
解説: 背景や設計の理由を述べる文章を置く。

迷うときは読み手の目的で選ぶ。学ぶ・作業する・調べる・理解するのどれにあたるかで分ける。

ディレクトリはこの分類に対応させる。

docs/
├── architecture/          # 解説：システム全体像と意思決定
│   ├── overview.mdx       # C4 Context + Container レベルの全体図
│   └── decisions/         # ADR（連番）
├── reference/             # リファレンス：仕様・事実
├── how-to/                # ハウツー：課題解決の手順
└── guidelines/            # 解説：開発規約

チュートリアルは、このリポジトリが学習を目的としないため置かない。

重複の扱い

正本は1か所へ置く。これを Single Source of Truth と呼ぶ。既存の正本があるなら、新規に書かずリンクで参照する。手書きの文章では、ある程度の言い回しの重複まで機械的には排除しない。禁じるのは、同じ責務の正本が複数並ぶ状態である。

README の役割

README は入口に徹する。概要と最短の手順だけを置き、詳細は各ドキュメントへリンクする。

システム全体像の記録

システム全体像は C4 の Context・Container の2レベルで図示する。Component（コンテナ内部の構造）以下は、変更頻度が高くメンテコストも重いため書かない。

意思決定の記録

技術選定や設計判断の理由は ADR として architecture/decisions/ 配下に連番で残す。決定が覆っても削除せず、経緯を残す。

ADR のステータスは、その決定が現在も有効かを示す。次の値で表す。

ステータス	意味
提案中	起草済みだが、まだ合意していない
承認済み	合意され、現在有効である
却下	提案したが採用しないと決めた。判断の理由を残すため記録する
非推奨	もう推奨しないが、特定の後継 ADR はない
置換（ADR-NNNN へ）	新しい決定に置き換わった。後継の ADR へリンクする

決定が変わったときは、新しい ADR を起こす。古い ADR は本文を消さず、ステータスを「置換」に更新して後継へリンクする。