ドキュメント

自分のノートと『Google のソフトウェアエンジニアリング』第10章を1本にまとめたもの。書籍由来の主張は要約して (書籍10章) のように出典を付けた。本文の引用はしていない。

存在意義

頻繁に見られたり、更新されているかどうか
ほとんど見られたり、更新されないものは不要
更新頻度が低くても、長く使われているものもある

書籍が挙げる効能はこう。(書籍10.2)

なぜその設計にしたのか、なぜその実装にしたのかに答えられる。 2年後の自分に対しても効く
API を扱いやすい形に定式化する助けになる
保守のロードマップと履歴の記録になる
しっかり書かれた API は、設計も良いだろうと推測される
他のユーザーからの質問が減る。書く側にとってはこれが最大の見返り

なお書籍の定義では、ドキュメントは独立した文書だけを指さない。 コードのコメントも含む。実際、Google のエンジニアが書くドキュメントの大半はコメントの形で現れる。(書籍10.1)

コードと一緒に管理する

リポジトリと別で見る人と更新する権限のある人が別のドキュメントは保守されにくい
リポジトリとは別にしない
コードと同じところで管理する

書籍の言い方では、ドキュメントはできるだけコードとして扱う。(書籍10.3) 具体的には、次の条件を満たす状態にする。

従うべき内部的なポリシーかルールを持つ
ソースコントロールの管理下に置かれる
保守する責任を持つ明確なオーナーがいる
変更がレビューを経る(そして対象のコードと一緒に変更される)
コードのバグと同じようにドキュメントの問題が追跡される
定期的に評価される(ある意味でテストされる)
可能なら正確性や鮮度が計測される

オーナーのいないドキュメントは鮮度を失い、保守が難しくなる。

置き場所は、ドキュメント化している対象のソースコードと同じ場所が理想。

ドキュメントを「ソフトウェア開発に必要なタスクのひとつ」として扱うエンジニアが増えるほど、書く先行コストへの不満が減り、回収できる長期的利益が増える。だから書くタスク自体を簡単にすることにも意味がある。

書式

統一されているかどうか
Markdownになっているか

Google も共通の書式整形言語として Markdown を導入している。(書籍10.3)

対象読者を決める

最も重大な失敗は、自分のためだけに書くこと。 (書籍10.4) 自分のために書くこと自体が無益なのではなく、主要な対象読者を特定して、その人に向けて書く。

肝に銘じるべき非対称性がある。 読者はかつての自分と同じ位置にいるが、自分が最近身につけたドメイン知識を持っていない。

何のためのドキュメントか

読む対象者
前提知識、どの程度の知識レベルにある人向けか
同じユニット向けか、別のユニット向けか、世間一般向けか
ドメイン知識のある人向けか、ない人向けか

読むのにどれくらい時間がかかるか
読んだら読者はどうなるか、何を得るか

利用者向け(API ユーザー)と提供者向け(プロジェクトメンバー)は、できるだけ分ける。 (書籍10.4.1)

設計上の決定の根拠は、本文に混ぜずにデザインドックへ、あるいはインターフェイスの背後に隠れた実装コメントへ置く方が適切。

簡潔で短く、明確に

冗長にかかれていないか
熟練者を苛立たせないか
何から何まで詳細に書いていないか

要点は書かれており、非熟練者でも理解できるか

簡潔に短く、明確に書かれているか

大枠と注記で全体的にバランス良くなっているか
すべて細かく書かれていないか

Perfection is achieved when there is nothing to take away（完璧とはこれ以上削れない状態の事である）
less is more(より少ないことがより良い)

書籍も同じ結論に達している。専門家向けに省略すると初心者が混乱し、初心者向けに全部書くと専門家が苛立つ。この両方を同時に満たす方法が「短くすること」。 (書籍10.4.1)

短く書く手順も具体的に示されている。 まず全情報を入れた長いドキュメントを書き、そこから編集工程で重複を可能な限り削る。 最初から短く書こうとしない。

重複していないか

すでにある場合は追記
だいたいすでにある

複数の重複したものがある場合は最新で最もよく使われているもの以外は一意的な内容を移動のうえ削除する

ないときだけ新規作成

書籍の手順も同じ形。主要な情報源を1つ決め、他の関連する情報源をそこへ整理統合するか、重複分を廃止する。 (書籍10.3)

そして 1つのドキュメントには唯一無二の目的を持たせる。(書籍10.5) 複数の目的が入っているなら、論理的な形で分割する。何十画面もスクロールできて、切れたリンクだらけの wiki ページが典型的な失敗例。

5W1H で埋まっていないところを探す (書籍10.7.1)

大多数の技術文書は HOW にしか答えていない。どう動くのか、この API にどうプログラムするのか、このサーバーをどう設定するのか。

抜けやすいのは残りの5つ。

	決めること
WHO	対象読者は誰か
WHAT	このドキュメントの目的は何か
WHEN	いつ作成・レビュー・更新されたか
WHERE	どこに置くか。理想は対象のソースコードと同じ場所
WHY	読み終えた読者に何を覚えていてほしいか

WHY は導入部で確立するのが経験則上よい。

構成: 始まり・中盤・終わり (書籍10.7.2)

最初の節  問題を示す
中盤の節  推奨される解法を見ていく
結論      覚えておくべきことを要約する

節の中も同じ形にする。導入の段落で要点を紹介して要約し、残りでその主張を詳細に述べる。ここでの冗長性は、重要性を読者に伝える働きをするので削らない。