文書は「なぜそうしたか」に後から答えるためのもの。コードと同じ流れで管理し、読者と目的を絞って書き、役目を終えたら消す。
目次
文書もコードと同じ流れに乗せる
ソース管理・オーナー・レビューを付け、コードと一緒に変える。
- オーナーのいない文書は古びる
- 情報源が複数あるなら主要な1つに寄せる
- 置き場所はコードのすぐ隣がよい
読者を1人決めて、短く書く
自分のためだけに書くのがいちばんの失敗。
- 読者は自分が最近覚えたことを知らない前提で書く
- 全部書いてから削ると短くしやすい
- 利用者向けと、中を触る人向けの文書は分ける
1つの文書に目的は1つ
目的が混ざると、長くてリンク切れだらけのページになる。
| 種類 | 書き方 |
|---|---|
| リファレンス | コードのコメントから生成する |
| 設計書 | ゴールと、代案の長所・短所 |
| チュートリアル | 前提知識を仮定しない |
| 概念の文書 | 完全さより明確さ |
| ランディングページ | 目的とリンクだけ |
書くとき・見直すとき・消すとき
誰・何・なぜを冒頭で示し、役目を終えたら消すか古いと明示する。
| 問い | 中身 |
|---|---|
| 誰が | 対象読者 |
| 何を | 文書の目的 |
| いつ | 作成・レビュー・更新日 |
| どこで | 理想は対象コードの隣 |
| なぜ | 読後に覚えていてほしいこと |
- レビューでは正確さ・明確さ・一貫性を見る
関連
- 知識共有 — 書き残すことと、人に聞くことの使い分け
- スタイルガイドとルール — 文書コメントと実装コメント
- テスト — 明確なテストは実行できる文書になる