理系のための文書作成術(1) ―― 開発文書を分かりやすく記述する

塩谷 敦子

tag: 組み込み

技術解説 2010年8月11日

●改善してみましょう

 次に,例文の改善案を考えてみましょう.例えば,(問題点3)で指摘した点,すなわち「電源がONのときの」を事象(イベント)の表現として改善してみましょう.例文には種々の問題があるとしても,「初期化処理」を行うことだけは確かな意図として読み取ることができます.そこで,「電源がONのときの」を改善して,事象の表現として適正な意味を持つように記述してみます.

  • (案a)「電源がONになったときの初期化処理を実施する」
    「電源がONになったときの」が「初期化処理を実施する」という記述に適切に繋がってきます.
  • (案b)「電源がONになったときに行うことになっている初期化処理を実施する」
    (案a)の「の」が意味しているところをより明確に示しています.
  • (案c)「電源がONになったときに初期化処理を実施する」
    いつ「初期化処理を実施するか」を特定できる表現となっています.

 (案a)(案b)は,「電源がONになった」という事象を示す正しい表現に変更しています.しかし,この事象の表現に「ときの」や「ときに行うことになっている」を繋いで,「初期化処理」を修飾する形容句としていることには変わりありません.つまりこれは,「実施する」を修飾しているわけではないので,「初期化処理」を,いつ,どんなときに,実施するかを明示していません.「初期化処理」の実施タイミングに関しては,例文中に記述を追加するか,他の場所で明示することが望まれます.この点からすれば,(案c)はより明確な改善案になります.

 さらに,ソフトウェア開発文書として,この例文の前後には,「電源がONになったとき」とは,具体的にどんなときなのかを示すことも必要となるでしょう.例えば,「電源がONになったとき」とは,次の場合が考えられ,これらは同意ではありません.

  • 電源投入時
  • 電源がONに変わったとき
  • 電源を(何某が)ONにしたとき

 これらのいずれであるかを明示することも,開発文書として分かりやすい(迷いのない正確な)記述と言えます.

●読み手に推測させない開発文書を書きましょう

 書き手が,「こういうつもりで書いた」と言っても,読み手にその通りに伝わらなければ,文書としての意味をなしません.ましてや,分かりにくい点を読み手に推測させて開発が進んでいくようなことがあってはなりません.読み違いによって,求められているものとは全く異なるソフトウェアを開発してしまった,という事態にもなりかねません.

 分かりにくい開発文書が,ソフトウェアそのものの品質低下につながる危険性を十分に持っていることを,ぜひ意識してください.読み手に推測させない,誰がいつ読んでも同じ解釈ができるような開発文書を作成することが重要です.このために,開発文書を書くとき,また開発チーム内の文書を読むときに,分かりやすさ(正確であること,読みやすいこと,目的に合っていること)を心がけてみてください.これが,モノづくりにおいて,分かりやすいモノ(ソフトウェアなど)を分かりやすく作ることに確実につながっていきます.

 次回は,開発文書内で図表を書く際のヒントを,組み込みソフトウェア開発の記述例を使って紹介します.

参考文献
(1)藤田 悠,山本 雅基,中澤 達夫,塩谷 敦子,池田貴一,楡井雅巳;組込みソフトウェア開発文書診断法,情報処理学会研究報告,Vol.2010-EMB-16,No.37(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日