プログラム開発者向け仕様書の書き方
−「読者の視点」と「製品の動作」で構成する−

「プログラム開発者向け仕様書」の執筆者と読者

ここで述べる「プログラム開発者向けの仕様書」の執筆者は、アプリケーションソフトウェアを開発するのに必要なソフトウェアのパッケージ（ソフトウェア開発キット、通称SDKに類するパッケージ）を提供するメーカの技術者です。対して、読者はエンドユーザ向けのアプリケーションソフトウェアを開発するプログラマです。執筆者も読者もプログラム言語の知識を有する技術者です。しかし、読者は執筆者の「論理」で開発かつ命名されたプログラムコンポーネントの動作と使い方を理解し、これらを組み合わせてエンドユーザ向けの製品の機能を開発しなければなりません。

• 前述の「機能仕様書」は、これから製品を開発する技術者間で仕様を周知するための文書です。したがって、その「主たる視点」は「（製品をともに開発する）私たち」です。同じように「仕様書」とよびますが、ここで述べる「プログラム開発者向け仕様書」とは位置付けが大きく異なります。

• 混同を避けるために、「機能仕様書」を「要件定義書」もしくは「開発仕様書」、対して「プログラマ向け開発仕様書」を「プログラム開発ガイド」とよぶメーカもあります。

執筆者が提供するプログラムコンポーネントは、主たる用途を想定して開発されていても、その組合せ方はプログラム開発者がエンドユーザ向けの製品に実装する機能によって決まります。プログラム開発者が目指すのは、プログラムコンポーネントの動作によりエンドユーザが必要とする機能をいかに実現するかです。

「エンドユーザ向け製品解説・マニュアル」との違い

“使う人”が読者という点では、両者の「主たる視点」は「あなた」です。ただし、「製品の動作」を表す際にエンドユーザ向けの製品解説・マニュアルでは「ユーザによる操作の結果」として表すのが一般的ですが、プログラマ開発者向け仕様書では「プログラムコンポーネントの定性動作」として表すのが通例です。

• プログラマ開発者向け仕様書では、「（ある条件で）＊＊クラスは＊＊＊を取得する」など「主語−目的語−述語」で表します。

エンドユーザ向けの製品解説・マニュアルとプログラム開発者向けの仕様書の違いは、“ブラックボックス”の外側と内側の違いであると言えます。プログラム開発者向けの仕様書では、ある機能を構成する際に必要な“複数の”プログラムコンポーネントの動作の関係（ブラックボックスの内側）が主たるテーマです。対して、エンドユーザ向けの製品解説・マニュアルでは、ユーザから見た“一つの”製品（いくつもの機能が集約された）の動作が主たるテーマです。

• 携帯電話のソフトウェアを開発するためのSDK（プラットフォーム、ライブラリなど）があるとします。プログラマは、複数のプログラムコンポーネントを用いてアプリケーションプログラムを作成して機能を実現します。この際、それぞれのプログラムコンポーネントの機能は「動作」としてとらえます。したがって、プラットフォーム上では数百あるいはそれ以上にさまざまな動作の主体によるいくつもの動作が実行されると言えます。

• 対して、エンドユーザが携帯電話を使う際、「動作の主体」は液晶画面が基本です。その他の動作の主体はいくつかのランプとスピーカにすぎません。入力キーあるいはマイクは入力部であって操作の対象です。したがって、「選択すると、液晶画面が＊＊設定画面を表示します」とはせず「選択すると、＊＊設定画面が表示されます」と受け身文で表します。

プログラムコンポーネントの「動作」の表し方

上述のように、エンドユーザ向けの製品解説・マニュアルでは、「動作の主体」となる製品は“ほぼ一つ”に集約されます。対して、プログラマ開発者向け仕様書では「動作の主体」は多数（場合によっては数百）です。この違いから、「主たる視点」が「（“使う人”である）あなた」であっても、製品の動作の表し方が異なります。

• たとえば、「表示」という動作を取り上げても、エンドユーザ向けの製品ではその「動作の主体」はとくに明示しなくとも製品本体です。したがって、「製品が＊＊を＊＊に表示します」とせず「＊＊に＊＊が表示されます」で済みます。一方、プログラマ開発者向け仕様書では｢表示」の「動作の主体」はいくつもあります。したがって、「ABCクラスがabcを表示します」、「DEFクラスがdefを表示します」と表す必要があります。

• しばしば、エンドユーザ向けの製品解説・マニュアルで「HIJ画面にhijが表示されます」と「HIJ画面がhijを表示します」が混じっているのを見かけます。これは、技術者がプログラム開発者向けの仕様書との位置付けの違いを考慮せず、曖昧に混用している例と言えます。

整理すると、プログラマ開発者向け仕様書では主たる視点をエンドユーザ向け製品解説およびマニュアルと同じく「あなた」とし、製品の動作を表す際は機能仕様書と同じく「製品の定性動作」で表すのが適当です。

• プログラム開発者向けの仕様書は、機能仕様書に準じた見出しで構成されるのが一般的ですが、読者にとって「何であるか／使うことの必要性・有効性」を述べるには製品解説およびマニュアルに準じた文体で表すのが適当です。ただし、先に述べたように動作の主体が複数ありそれぞれが相互に作用する関係にあるため、製品の動作を表す際は「主語−（目的語）−述語」とした主語を明確にした能動文で表すのが原則です。

いずれの文書も、段落を「人の行為」と「製品の動作」で構成する点で共通です。この際、それぞれが曖昧に混在すると「述語」が人あるいは事物のいずれを主語にしているかが曖昧になってしまいます。とりわけ、プログラマ開発者向け仕様書では、人が主語とも事物が主語ともとれる述語（例：実装する）を用いる場合があります。「主語を省略せず能動文で表す」を原則とするとともに、述語に用いる動詞・助動詞を選別する必要があります。

• たとえば「行う」は、本来は人を主語にして用いるべき動詞です。主語を曖昧にして「-を行う」とすると、「プログラム開発者に指示している」とも「プログラム開発者が意図して行う」さらには「主題になっている事物が定性的に動作を“実行”する」とも二重三重に受けとられるおそれがあります。

次ページに進む（ボタンをクリックしてください）

実践テクニカルライティングセミナー
マニュアル作成の進め方とわかりやすいマニュアルのポイント
Copyright: Takaaki-YAMANOUCHI/1995-2020
山之内孝明／有限会社　山之内総合研究所
Takaaki Yamanouchi/ Yamanouchi Research Institute, Ltd.