469行に膨らんだ台帳をDiátaxisで3冊に割った — Markdownだけのドキュメント管理

開発が進むとドキュメントは必ずだれる。rustx86 では性能台帳の perf.md が469行に膨らみ、開いても目当ての数字にたどり着けなくなった。ツールを導入せず、分類の型 (Diátaxis) と運用規約6条だけで立て直した記録である。

だれの正体: 地図と物語と化石の同居

469行のperf.mdを読み直すと、3種類の文章が混ざっていた。

• 地図: 現在地の数字、最適化カタログ、測定の規律 — 「引く」ためのもの
• 物語: 「カバレッジ1.2%の謎解き、犯人は4人いた」— 日付つきの実験記。「読む」ためのもの
• 化石: 3日前の「現在地」、役目を終えた段階計画、後の決定と矛盾したままの行

引く文書に物語が挟まると検索性が死に、物語に地図が挟まると読み物として途切れる。そして両方が同居した文書は更新時にどこへ書くか迷い、化石が堆積する。だれの正体は「役割の混在」だった。

Diátaxis — 文書を読者の目的で4つに分ける

Diátaxis はドキュメント分類のフレームワークで、Djangoなど大規模OSSのドキュメント再編で実績がある。全文書を読者の目的で4象限に分ける:

肝は「読み物と引くものを混ぜない」の一点である。rustx86のdocsはこう載った:

実際の分割: perf.md → 3冊

469行の1ファイルを、役割で3つに割った:

化石はこのとき削るか実験記へ移した。行数の合計はほぼ変わらないのに、どのファイルも一気に読める長さになったのがポイントである。だれは量の問題ではなく混在の問題だった。

pitfalls.md には書式も決めた: 型 (規則の一文) → NG/OKのサンプルコード → 事件 (実話) → 検知法。散文よりコピペできる形が効く。筆頭は「setTimeout(fn, 0) のループは4msずつ止まる」— 教科書どおりに書いたのに罠だったもの、が一番価値が高い。

運用規約6条 — 再発防止

分割しても規則がなければまた混ざる。索引 (docs/README.md) に運用規約を明文化した:

1. 1ファイル1役割 — 地図と物語を同じファイルに書かない
2. 実験の経過はperf-logへ追記 — 地図側はカタログの状態欄を1行更新するだけ
3. 横断の教訓はpitfallsへ — プロジェクト固有のものは載せない
4. 決定はADRへ、追記はしても書き換えない — 「効いたのに見送る」判断は賛否の議論と復帰条件まで書く
5. 索引は1本だけ — 目次を二重に持たない (二重に持つと必ずズレる。実際ズレた)
6. サイト生成ツールは入れない — mdBookは綺麗だが「ビルド工程」という運用が永続する。GitHubが素のMarkdown+Mermaidを描画してくれる限り不要。公開教材としてサイト化したくなったときに再判断

ツールより先に型 — という判断について

「ドキュメント管理」で検索するとツール (mdBook, Docusaurus, Notion, …) が出てくるが、だれの原因が役割の混在なら、ツールを替えても混在は持ち越される。逆に型さえあれば、プレーンなMarkdown+GitHubで十分に回る。

これはこのリポジトリの最適化方針と同型の判断である — 少し前に、実測-25%のPGOを「運用判断を半永久に持ち込む」ことを理由に見送った (ADR-0009)。ドキュメントも同じで、一度入れたら終わりの「型」を先に、運用が発生する「ツール」は本当に必要になってから。

ADRについて一つだけ

今回の再編で一番効いている文書はADRだと思う。とくに「やらないと決めたこと」のADRである。効いた最適化を見送る、有望な路線を凍結する — こうした判断は記録がないと、後から見た人 (未来の自分を含む) が「なぜ無いのか」を疑い続けることになる。賛成論・反対論・決め手・復帰条件まで書いた1枚があるだけで、見送りは「損失」から「整理」に変わる。

リポジトリ

github.com/yoshiharu-ishii/rustx86/docs — 索引・規約・分割後の実物はすべてここで読める。