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

塩谷 敦子

tag: 組み込み

技術解説 2010年9月13日

●ちょっとした意識が図表を生かす

 さらに,これらの基本ルールに加え,ソフトウェア開発文書の分かりやすい記述として,いくつかの意識すべき点を紹介します.

・図表は固有名詞で命名しよう
 図表のタイトルに,一般的な名詞を用いていませんか.例えば,「プログラム構造図」,「状態遷移表」などです.記述された図や表を見れば分かるようなタイトルは,付ける意味がありません.タイトルは,図や表を命名するつもりで決めましょう.命名するということは,その図表を他の図表と識別できるようにするということです.ですから,タイトルにはぜひ固有名詞を入れてみましょう.例えば,例に挙げた「プログラム構造図」,「状態遷移表」は,「AAAプログラムの構造図」,「BBB処理の状態遷移表」と固有名詞を入れる方が,適切なタイトルになります.

 このように固有名詞を図や表のタイトルに入れることで,図や表の識別が容易になり,文書内で必要な図や表へのアクセスも容易になります.文書の目次には,章節の目次以外に,図目次や表目次を入れることがあります.図目次や表目次があると,図や表の一覧を把握でき,また各図表を参照しやすくなります.このときに複数の図に同じタイトルがついていては,どの図や表を参照するべきなのか分からず,目次として意味のないものになってしまいます(図7).


図7 図のタイトルだけでは参照が困難な例

・図表の記載目的を明示しよう
 図や表を記載しておきながら,その掲載意図に言及せずに本文の記述を進めることは避けましょう.読み手が,記載されている図や表の位置付けを全体の記述中で理解できないままに読み進めなければならないような書き方は好ましくありません.ときどき,図8のように,図や表しか記載されていない章や節を見かけます.特に,要求定義書や設計書では,要求定義者や設計者の意図を,図や表だけで伝えることが困難な場合がほとんどです.この章で何を定めるか,そのために,章や節また本文にとって,図や表にどのような意味を持たせるのかを明示する必要があります.


図8 節の中が図だけの記述例

 開発文書において,図や表は,開発の過程で決めた事柄を明示したり,理解の助けとする手段です.そこで,「○○を記述するために図1を用いる」,「決定した○○を表1に示す」などと,「なぜここでこの図や表を使うのか」が分かるように記述しましょう.これが掲載意図を書くということです.開発文書では,図や表を書くことが直接の目的ではないはずです.図や表を書くことで何を表現するかを明確にしなければなりません.

・図表は表現の手段にすぎない
 前項で,図や表を書くこと自体が記述の目的ではない,とお話しました.開発文書に書くべきこと,すなわち「ここでは何を書くか」といった記述の目的は,開発作業過程で定義したことや設計したことを書き示すことです.対象とするソフトウェア開発の中で,「定義したこと」「設計したこと」が何であるかを明確にしなければ,何を書くのかがボケてしまいます.

 最近,図や表を用いて,仕様定義や設計作業を進める人が増えてきました.ソフトウェアの開発作業に適するモデル化の手法も多く提案されています.図や表が,開発を効率的に進めるために,非常に有効な表現の手段になってきています.ここで,図や表が「表現の手段」であることに注意してください.

 「あいまいな仕様を図によって明確化した」と言っている開発者の言葉を耳にすることがあります.これは,「図によって明確になった」わけではなく,図で表現しようとしているうちに,思考が明確になってきて,定義すべきことが整理されてきたのではないでしょうか.分かっているつもりで図に書いてみたらうまく書けなかったことで,実は分かってはいなかったことや,自身の思考のあいまいさに気付くことがあります.図や表に表そうとすることで,どこがあいまいであったかを見つけ,そこを明確にしようとしたのだと思います.

 仮に,書き手の思考にあいまいさが残っていたとしたら,そのあいまいさを図や表で埋めることはできないはずです.特に,図は,思考を抽象化表現したものと言えます.図の種類にもよりますが,図にはあいまいさを埋めるどころか,思考のあいまいさを隠してしまう危険があります.開発文書として図だけを引き渡すような開発の進め方をしているプロジェクトで,図の中の隠れたあいまいさがそのまま引き渡され,下流の工程になって初めてそのあいまいさに気付く例も,筆者は多く見てきています.

 図や表は,表現の手段にすぎません.図や表自体が,設計する対象ではなく,また設計結果を生み出すものでもない,ということを,常に念頭に置きましょう.そして,図や表で何を表現するかを明確にして,それを開発文書に明示しましょう.このことは,書き手自身が,開発作業の中で何をするべきかを明確に理解することにつながってきます.開発者の仕事は,「AAAの構造図を書く」ことや,「BBB処理の状態遷移表を作る」ことではありません.「図を使って,AAAの構造を定義する」,「表を使って,BBB処理の状態と事象の関係を取り決める」ことであるはずです.

***

 次回は,文書作成を仕事にとりこんでいくコツを,開発作業を例にして解説します.

参考文献
(1)木下是雄;『理科系の作文技術』,中公新書,1981年.
(2)APA(アメリカ心理学会);『APA論文作成マニュアル』,医学書院,2004年.
(3)日本工業規格;『日本語文書の組版方法』, JIS X 4051:2004,2004年.
(4)合同会社イオタクラフト;組込みソフトウェア技術者研修 「ソフトウェアドキュメンテーション」テキスト,合同会社イオタクラフト発行, 2008-2010年.

 

しおや・あつこ
イオタクラフト

組み込みキャッチアップ

お知らせ 一覧を見る

電子書籍の最新刊! FPGAマガジン No.12『ARMコアFPGA×Linux初体験』好評発売中

FPGAマガジン No.11『性能UP! アルゴリズム×手仕上げHDL』好評発売中! PDF版もあります

PICK UP用語

EV(電気自動車)

関連記事

EnOcean

関連記事

Android

関連記事

ニュース 一覧を見る
Tech Villageブログ

渡辺のぼるのロボコン・プロモータ日記

2年ぶりのブログ更新w

2016年10月 9日

Hamana Project

Hamana-8最終打ち上げ報告(その2)

2012年6月26日