理系のための文書作成術(1) ―― 開発文書を分かりやすく記述する
●改善点を見つけてみましょう
次の例文は,筆者がある組み込みソフトウェア開発の仕様書内で見つけた記述です.分かりにくい個所を指摘してみてください.
本モジュールでは,電源がONのときの初期化処理,電源ライト点灯処理を実施する.
短い1文の中で,いくつの分かりにくい点が見つかりましたか.実際の仕様書では,この文の前後にも記述が存在します.1文だけでは分かりにくい(一意に解釈できない)点であっても,文脈から判断できる場合もあります.ここでは,他の個所の記述によって想定できる点は除き,1文のみから読み取れる改善点を指摘してみましょう.例えば,例文中の「初期化処理」という表現において,「何を」初期化するかは他の個所に記載されているものとします.
筆者は,この1文から,改善できそうな点を4点見つけました.
例文では,次の3通りの解釈ができてしまいます.
- 言い換え:「初期化処理として電源ライト点灯処理を実施する」
- 並列:「初期化処理と電源ライト点灯処理を実施する」
- 順接:「最初に初期化処理を実施し,続いて電源ライト点灯処理を実施する」
複数の事柄を並べて記述するときには,それらの事柄同士が意図と異なる関係に解釈されないかに注意して,あいまいさを避ける記述を心がけましょう.
「初期化処理」だけにかかるように読みとれます.しかし,「初期化処理」に加えて「電源ライト点灯処理」にもかかるととらえることもできてしまいます.
このように,複数の解釈を誘う記述は,開発対象であるソフトウェアを意図しない仕様のものに導いてしまいます.そして,分かりにくい記述を含む仕様書は,開発のための重要な情報を明確に示せずに,かえって開発の妨げになる危険性を持っています.
このような改善するべき記述の検出には,特別なソフトウェアの知識は必要ありません.日本語表現として分かりにくい点を指摘することが,ソフトウェア開発上のあいまいさを発見することにつながります.