ドキュメントの作成について
ノウハウの蓄積や仕様書の作成など、ドキュメントを整備し始める時、何にも考えずに書き始めてしまうと後になって破綻する。
問題点：
- どこに何が書いてあるかわからない
- ↑で文書ごとの住み分けがあいまいになる
でグダグダになって、
- 読むほうもアテにしなくなる
- 書くほうもめんどくさくなる
と言うのが同時進行しがち。どんどん品質が落ちてくる。ていうかグダグダになりつつある状況で、最後まで辿り着くことすら出来ない場合が多分多い。
上記のやり方は
- 大項目ごとに文書を分ける
- 後は適当
と言うやり方。ここまで来るともう何が悪いのかは自明で、最初の「設計」の時点でもう少し「詳細を絞り込め」ば良い。
これは多分色々やり方があると思うけど、ここは一つ慣れ親しんだ ER やクラス図の要領で書いてみるとよいかなと、要はそう言うことを思いついた。
文書タイトルが表名やクラス名に相当し、章がフィールドやプロパティに相当する。どこまで落とせるかの粒度によってだけど、この手の図ならフィールドごとの関連なども線などで書き表す事が出来ると思う。*1
こうして俯瞰するのを容易にしてしまえば、当初の問題点は無くなる。メンテも楽だ。ドキュメント利用者向けの地図としても活用できるかも知れない。
だめかなあ？箇条書きの群れを図にして扱うという思いつきと言うか焼き直し。
追記：いや、考えてみたらクラス図ってのはもっぱらこう言った用途に使うべき物だったなそういえば･･･。以外と忘れがちな事実なのでこのまま置いとく。
*1:当然メモだって貼れる
