READMEに全部書こうとして、
後から自分で読むのが一番つらくなったことはありませんか。
自作ツールをGitHubに公開するとき、READMEに全部書こうとして破綻した経験はありませんか。
本記事では、未来の自分と他人を同時に助けるための「ドキュメント分割設計」を整理します。
例えば
README がどんどん巨大化していき、
- どこに何が書いてあるか分からない
- 書いた本人ですら更新が怖い
- 結果、誰にも読まれない
──そんな状態になりがちです。
この記事では、
自作ツールを公開する際にドキュメントが破綻しないための分割設計について、
実体験ベースで整理します。
技術解説ではなく、README・docs・設計書をどう分ければ壊れないか、という話です。
私が整理中のGithubリポジトリをサンプルにしてみました
- 整理途中
- ドキュメントが破綻している
結論（先に言い切る）
ドキュメントは「読む順番」と「責任範囲」を固定しないと破綻する
技術力より大事なのは、次の3点です。
- どこに何が書いてあるか
- それは誰が読む前提なのか
- どこまで読めば次に進めるのか
これを決めずに書き始めると、
最終的に一番困るのは未来の自分になります。
この記事の主軸にしたい問い
この記事の軸はこれです。
「GitHubに自作ツールを置くとき、
README / docs / 設計書 をどう分ければ“壊れない”のか？」
これは、
- チーム開発をしている人
- 運用保守している人
- OSS初心者
- 個人開発者
- PoCを量産している人
全員が一度は直面するテーマだと思います。
ドキュメンテーションを「役割」で分割する
① README.md は「契約書」
README に期待されている役割は、実は多くありません。
README の役割は3つだけです。
1. これは何か
2. 誰向けか / 誰向けじゃないか
3. どうやって“最低限”動かすか
逆に、README に書かなくていいものは明確です。
- 詳細仕様
- 実装理由
- 内部構造
これらは全部 README に書かない。
README が肥大すると、ほぼ確実に次の状態になります。
- 最後まで読まれない
- 更新されなくなる
- いつの間にか嘘を書く
README は「入口」であって、「全集」ではありません。
② docs/ は「知識の倉庫」
詳細な情報は docs/ 配下に逃がします。
重要なのは、
docs 配下は「読む順番を想定しない」ことです。
例：
- Architecture.md
- DatabaseDesign.md
- CollectionLogic.md
- TriggerSpec.md
- APISpec.md
ここに置くドキュメントは、
- 後から参照する
- 必要な人だけ読む
- 途中から読んでもいい
という前提で作ります。
位置づけとしては 「辞書」「リファレンス」 に近いです。
README からは
「詳しくは docs を参照してください」とリンクするだけで十分です。
③ Roadmap / Management 系は「未来の自分への手紙」
個人的に一番重要だと思っているのがここです。
- なぜこの設計にしたのか
- 何をやらないと決めたのか
- どこで悩んでいたのか
これらは、コードにも README にも残りません。
しかし 3か月後の自分は、
他人と同じくらい何も覚えていない
という現実があります。
- Roadmap.md
- ProjectManagement.md
- CHANGELOG.md
こういったドキュメントは、
未来の自分を助けるために書くものだと思っています。
他人が困らないドキュメントの条件
条件①「読まなくていいもの」が明示されている
ドキュメントにおける優しさとは、
読ませないこと
です。
README に、これを書くだけで効果があります。
まずは README だけ読めばOKです
docs/ は必要になったら参照してください
「全部読まないと分からない」状態が、一番のストレスになります。
条件②「正確さ」と「分かりやすさ」を混ぜない
よくある失敗がこれです。
- 分かりやすく書いた結果、仕様が曖昧
- 正確に書いた結果、誰も読めない
混ぜるな危険
割り切って分けます。
- 正確性：docs/
- 分かりやすさ：README / Qiita
役割を混ぜないことで、更新も楽になります。
条件③「なぜ存在するか」を別ドキュメントに逃がす
思想や背景を README に書き始めると、確実に長くなります。
その場合は、
- Motivation.md
- Background.md
のように専用ドキュメントを切るのがおすすめです。
読む人だけ読めばいい、で十分です。
実践的な“壊れない”構成テンプレ
実際に落ち着いた構成例です。
.
├── README.md # 最短導線
├── docs/
│ ├── Architecture.md
│ ├── DatabaseDesign.md
│ ├── CollectionLogic.md
│ ├── TriggerSpec.md
│ └── APISpec.md
├── Roadmap.md # 未来の自分用
├── ProjectManagement.md
└── CHANGELOG.md
ポイントは以下の3つ。
- README を“薄く保つ”
- docs を“増やすことを恐れない”
- 更新頻度が違うものを混ぜない
自作ツール公開で一番困るのは誰か
最後に。
自作ツールのドキュメントで一番困るのは、
- ユーザーでも
- コントリビューターでもなく
数か月後の自分です。
未来の自分は、
今のあなたが思っている以上に他人です。
だからこそ、
- 読む順番
- 責任範囲
- 書かない勇気
これを決めてから書くことが、
結果的に「他人に優しいドキュメント」につながります。