理系のための文書作成術(2) ―― 図表を表現手段として活用する

5．図には凡例を入れる
想定する全ての読み手が，図を構成する要素や記号の意味を一意に解釈できるように，図には凡例を入れます．凡例とは，図の中で使用する記号の意味を説明するものです．図4に，凡例の入っていない図を示します．これでは，この図をどう読めばよいのかが分かりません．

図4　凡例が必要な図の例

　そこで，図5のように凡例を入れてみます．凡例によって，図の意味するところが明確になりました．

図5　凡例を追加した図の例

　文書の読み手として想定できる全ての人が図の中で使用されている記号の意味を理解しているなら，凡例は必要ないでしょう．しかし，読み手全員が記号の意味を理解しているとは限らないときには，凡例が必要です．図の凡例は，文書中の用語定義と同じです．文書の中で読み手に理解できない用語があるとき，その定義をするように，図を構成する要素の意味を明確にして初めて，図が一意に解釈できるものになります．

　特定のモデル表現を使う際には，そのモデル表現で規定された表記法を使うかと思います．このような場合にも，想定できる読み手全員がその表記法を理解しているのかを考慮するべきです．書き手と読み手の間では，特定の表記法を使用することの合意をあらかじめとっておくことが必要です．事前の合意がないのなら，文書内に「UMLの表記法を用いる」などと明記してください．暗黙の了解や，「読み手はきっと理解できるだろう」といった書き手の勝手な思い込みで図の表記法を押し付けることのないように注意が必要です．

6．表は最左列を軸とする
　表には，「最左列を軸とする」という原則があります．最左列を軸とするとは，一番左の列に置く項目を基準となるキーにして，右側の列に配置する項目を決めていくことです．明確な意図により，あえて原則を外れた記述をする，という場合もあるでしょう．しかし特別な意図がない限り原則を守ることは，読み手に余計な混乱を与えずに，分かりやすく伝えることになります．

　図6に示した例では，表のタイトル「非機能要件の一覧」に対して，「非機能要件」の項目が最左列にありません．表を非機能要件の一覧として記載するなら，最左列には，「非機能要件」の項目を置く方が，読み手は自然に理解できます．もし，表4自体が示すように，「品質特性」の項目を軸（最左列）にしたい場合は，表のタイトルを「表4 品質特性による非機能要件の整理」などとする方が自然な命名と言えます．

図6　表の軸とタイトルが符合していない例

7．表には空欄を作らない
　表には空欄がないように書きましょう．書き手は，記載しようとする表に，安易に，またはやむを得ず，空欄を残してしまうことがあります．特に，ソフトウェア開発では，さまざまな理由によって決定を後回しにする場合があります．例えば，要求仕様がはっきりと決まらないまま，開発をスタートせざるを得ない場合があります．あるいは，複雑な設計のために，他の部分を先に進めることもあります．このように，決定すべきことをまだ決めていなかったり，書き手が，記述に時間がかかることを理由に記入を後回しにしてしまうこともあります．あるいは，そもそも欄に該当する事柄が存在しないので，空欄とする場合もあります．

　しかし，開発文書は，読み手に対して次の工程の開発行動につなげるためのものです．読み手にとって，表の内容にある記述をどのように扱うかを明示しない空欄は避けるべきです．なんらかの理由で欄を埋められない場合には，その理由を入れておきましょう．例えば，未決定のために埋められないのなら，「未決定^注1：○月○日決定予定」と，空欄ではなくなるめども書いておくとよいでしょう．また，欄に該当するものがない場合は，空欄にしておくのではなく「該当せず」と欄を埋めるように心がけましょう．

注1："TBD"と記載する場合がある．TBD（To Be Determined）は，「現在未定であり後で決定する」という意．

　ただし，しばしば表内に補足用として設ける「備考」欄では，補足したい場合にのみ欄を埋めます．特に補足する事柄がない場合には空欄が許され，空欄自体が「該当事項がない」という意味を持ちます．