ソフトウェアアーキテクチャ その11 - 健全なドキュメントを書く7つのルール [arch]
今回は少し趣向を変えて，ドキュメントの書き方について取り上げたいと思う．
"Documenting Software Architectures" に記述されている，「健全なドキュメントを書く7つのルール (Seven Rules for Sound Documenation)」を紹介する．
ところでこのエントリーを書きながら，e-mail や Blog を書く時にも当てはまることがいくつもあると思った．
Reference:
Documenting Software Architectures: Views and Beyond,
by Clements, et al. Addison-Wesley 2003
--> Page 24 - 30
本書には，Appendix に ECS Software のアーキテクチャ仕様書がそのまま例として載っており，私もアーキテクチャ仕様書を記述する際に大いに参考にしている．
但し，本書には関わっている著者が多く，全体的に若干繁雑な内容になっていることは否めない．最初から最後まで読了するというよりは，必要に応じて適切な内容を参照するカタログ代わりに利用すると良いかもしれない．
こちらがその和訳本．
多くの技術書がそうであるように，この和訳書も日本語が非常に奇怪だ．特に本書はその傾向が顕著で，例えば linked list (リンクリスト) が「結合した一覧表」などと訳されている．特に本書に関しては，極力オリジナルを読まれることを強くお勧めする．
Rule 1: Write Documentation from the Reader's Point of View
(読み手の視点で書くこと)
当たり前のことに聞こえるが，驚くほど考慮されていないポイントである．
ドキュメントは，書かれる回数より読まれる回数の方が多いのだから (リビジョンを数えなければ書かれる回数は1回)，読み手にやさしい方がドキュメントとして効果的と言える．読み手に対する配慮が感じられるドキュメントは「そもそも読まれる」し，繰り返し読まれる可能性が高い．内部的な専門用語なども使わないこと．
書き手中心の一方的なソフトウェアドキュメントは，"stream of consciousness" か "stream of execution" の構成を取ることが多い．"Stream of consciousness" とは，書き手が考えた順に記すこと (書き手の頭の中の時系列)．"Stream of execution" とは，ソフトウェアが実行される順に記すこと．どちらの構成も読み手が必要な情報を探すのに苦労する．
Rule 2: Avoid Unnecessary Repetition
(不必要な繰り返しを避けること)
同じ種類の情報は，1つの場所に記録されるべきである．これはドキュメントの利用性を高めるだけでなく，ドキュメントを変更する際の容易性を高める．
同じ情報が繰り返される時は微妙に違う表現になっていることが多く，「意図的に繰り返しているのかどうか，そうであるなら違いは何なのか…」と，読み手を混乱させてしまう．
あえて反復することで読み手の理解を深めさせることもできるだろうが，やはり基本は同じ情報を1個所に集約させること．
但し「不必要な」繰り返しというところがポイント．例えば，同じ情報を違う視点で説明する時などに情報が集約されていると，読み手がいちいちページをめくって前の記述を参照しなければならない．読み手の「コスト」を考えて，情報を繰り返すことが有効なのかどうか判断しよう．
Rule 3: Avoid Ambiguity
(曖昧な表現を避けること)
そもそもアーキテクチャとは，ある程度細かい内容 (例えば実装時に気にすべきことなど) を排除し，システムの上流設計方針を決めるものだから，多少の曖昧さは持つものである．しかしながら，意図しない曖昧さ，特にドキュメントから2つ以上の解釈ができてしまうような曖昧さは避けるべきである．
表記は厳密に定義し，正確な意味付けを心がけること．
例えばただの箱と線で書かれた図を良く見るが，その「箱」は何を意味するのか (モジュール，オブジェクト，クラス，プロセス，関数，手続き，プロッセッサなど) ? その「線」は何を意味するのか (サブモジュール関係，継承，同期，排他，コール，利用，データフロー，プロセッサマイグレーションなど) ?
凡例を設ける，異なる視点を混ぜない (違う viewtype を同時に語らない)，図を書きっぱなしにするのではなくそれが何を意味するか解説する…などして，読み手ができるだけ簡単に表記の意味を捉えられるように心がけること．
Rule 4: Use a Standard Organization
(標準的な構成を取ること)
標準的，かつ計画的な構成の体系を確立すること．これは読み手にとって情報を探しやすくするだけでなく，書き手にとっても文書化のプランを立てやすくする．ドキュメントの各セクションで明かされる要素を明確にし，レビューしやすくすること．
内容の参照が容易になるようにし (ドキュメントは，端から端まで読まれるよりも，一部が参照されることの方が多いだろう)，未完成部分や分からない部分は白紙にするのではなく，TBD (作業途中) ということが分かるようにしておく．
ちなみに，本書が言うところの「標準的な構成」の例については 本書 I.2 (Page 39) を参照．
Rule 5: Record Rationale
(根拠を示すこと)
決定事項だけではなく，そこに至るプロセスも非常に重要である．将来同じような議論・検討をする可能性があるからだ．
決定に至るまでにどんな選択肢が他にあり，なぜそれらが選ばれなかったのか，といった記録を残しておくこと．これは長期的な運用において，時間の節約につながる．
Rule 6: Keep Documentation Current But Not Too Current
(最新を反映するべきだが，極端に最新を追いかけないこと)
不完全な，あるいは内容が古いドキュメントは真実を表していないし，使いものにならない．常に最新にアップデートされた，精密なドキュメントこそ有効なものである．
一方で，変わるかもしれない決定を反映して時間を浪費する必要はない．特に設計時は方針が頻繁に変わるだろうが，ドキュメントをその度に改編するのではなく，むしろソフトウェアと同じようにドキュメントに対しても明確なリリース方針を立てるべきだ．
Rule 7: Review Documentation for Fitness of Purpose
(目的に適合しているかレビューを行うこと)
書きっぱなしは良くないので，レビューを行うことは当然だとして．
そのドキュメントが必要な情報を含み，分かりやすく表現されているかどうか，本当に判断できるのは読み手側であろう．ならば，リリース前に極力対象とする読み手 (例えばコミュニティの代表者など) のレビューを受けることが望ましい．
